@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/lib/hosts/passthrough.js

@@ -29,6 +29,7 @@ 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';
+import { isKnownTopLevelCommand } from '../startup/command-registry.js';
 /**
  * First-class groups that run transparently on a remote via SSH when
  * `--host`/`--device` is present. Keep both canonical names and aliases
@@ -436,6 +437,15 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         if (!isAll && command !== 'routines')
             return false;
     }
+    // A command that does not exist is an unknown-command error, not a routing
+    // error. The router runs BEFORE commander parses, so without this gate a typo
+    // (`agents session resume --host box`) was answered with "does not support
+    // --host/--device" — a true statement about a command the user never typed,
+    // and the exact opposite of the truth for the `sessions` they meant, which
+    // does support it. Fall through so commander reports `unknown command` (and
+    // its did-you-mean). RUSH-2022.
+    if (!isKnownTopLevelCommand(command))
+        return false;
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec) {
         // Flag was accepted (no raw commander "unknown option") but this group has
@@ -532,20 +542,37 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     const doctorPath = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
         ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
         : undefined;
-    // Forward actor provenance (AGENTS_ACTOR*/GIT_*) across the SSH hop, merged
-    // UNDER the doctor PATH so that PATH still wins — without this the remote
-    // re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
-    // (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
-    // AGENTS_FLEET_REMOTE marks this as a fleet-dispatched `--host` run so the far
-    // side can gate consent-sensitive actions — the browser consent gate
-    // (lib/browser/remote-control.ts) reads it to allow/deny a cross-machine drive.
-    const env = withActorEnv({ ...doctorPath, AGENTS_FLEET_REMOTE: '1' });
-    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
-    const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
+    process.exitCode = streamAgentsOnHost(host, forwarded, {
+        remoteCwd,
+        interactive,
+        extraEnv: doctorPath,
+        remoteOs,
+        target,
+    });
+    return true;
+}
+/**
+ * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
+ * return the exit code. The single place the SSH hop is built, so every remote
+ * `agents` invocation carries identical env semantics.
+ *
+ * Forwards actor provenance (`AGENTS_ACTOR`/`GIT_` vars) across the hop, merged UNDER
+ * `extraEnv` so a caller-supplied PATH still wins — without this the remote
+ * re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
+ * (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
+ * AGENTS_FLEET_REMOTE marks this as a fleet-dispatched run so the far side can
+ * gate consent-sensitive actions — the browser consent gate
+ * (lib/browser/remote-control.ts) reads it to allow/deny a cross-machine drive.
+ */
+export function streamAgentsOnHost(host, forwardedArgs, opts = {}) {
+    const target = opts.target ?? sshTargetFor(host);
+    const remoteOs = opts.remoteOs ?? resolveRemoteOsSync(host.name);
+    const env = withActorEnv({ ...opts.extraEnv, AGENTS_FLEET_REMOTE: '1' });
+    const remoteCmd = buildRemoteAgentsInvocation(forwardedArgs, opts.remoteCwd, remoteOs, env);
+    const code = sshStream(target, remoteCmd, { tty: !!opts.interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
             chalk.gray(' Check: agents hosts check ' + host.name));
     }
-    process.exitCode = code;
-    return true;
+    return code;
 }

package/dist/lib/hosts/session-index.d.ts

@@ -11,6 +11,10 @@
  * issued from, so the run appears in that project's session listing like any
  * local run. The `[host/<name>]` label mirrors the cloud path's
  * `[cloud/<status>]` convention.
+ *
+ * `machine` is the dispatch host, not this box. Both the transcript and the
+ * version-isolated harness home live there; omitting it makes the SQLite upsert
+ * infer this box from the empty file path and sends recovery to the wrong home.
  */
 import type { SessionMeta } from '../session/types.js';
 import { type HostTask } from './tasks.js';

package/dist/lib/hosts/session-index.js

@@ -11,6 +11,10 @@
  * issued from, so the run appears in that project's session listing like any
  * local run. The `[host/<name>]` label mirrors the cloud path's
  * `[cloud/<status>]` convention.
+ *
+ * `machine` is the dispatch host, not this box. Both the transcript and the
+ * version-isolated harness home live there; omitting it makes the SQLite upsert
+ * infer this box from the empty file path and sends recovery to the wrong home.
  */
 import * as fs from 'fs';
 import { upsertSession } from '../session/db.js';
@@ -18,6 +22,7 @@ import { isSessionTrackedAgent } from '../session/types.js';
 import { localLogPath, updateTask } from './tasks.js';
 import { parseSessionIdMarker } from './session-marker.js';
 import { deriveShortId } from '../session/short-id.js';
+import { normalizeHost } from '../machine-id.js';
 /**
  * Build the SessionMeta for a host-dispatched run. Returns null when the run has
  * no captured session id (nothing stable to key/resume on) or its agent isn't a
@@ -38,6 +43,7 @@ export function hostSessionMeta(task, ctx) {
         // Remote transcript — no local file. Empty file_path is the sentinel the DB
         // stale-filter treats as "always live" (see module doc).
         filePath: '',
+        machine: normalizeHost(task.host),
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
         // The run's `--name` seeds the label (resolves `agents sessions <name>` and
         // `agents hosts logs <name>`); an unnamed host run falls back to the
@@ -109,6 +115,7 @@ export function registerInteractiveHostSession(ctx) {
             timestamp: ctx.createdAt ?? new Date().toISOString(),
             cwd: ctx.cwd,
             filePath: '',
+            machine: normalizeHost(ctx.host),
             label: ctx.name || `[host/${ctx.host}]`,
         }, '');
     }

package/dist/lib/manifest.d.ts

@@ -3,8 +3,18 @@ import type { Manifest } from './types.js';
 export declare const MANIFEST_FILENAME = "agents.yaml";
 /** Parse a YAML string into a typed Manifest object. */
 export declare function parseManifest(content: string): Manifest;
-/** Serialize a Manifest object to a YAML string with 2-space indentation. */
-export declare function serializeManifest(manifest: Manifest): string;
+/**
+ * Serialize a Manifest to YAML WITHOUT destroying hand-written comments.
+ *
+ * Plain `yaml.stringify(manifest)` drops every comment, so `agents mcp add`
+ * (and every other writeManifest caller) used to clobber annotations in
+ * agents.yaml. Matching `serializeCentral` in state.ts: when existing file
+ * text is provided, parse it into a `yaml.Document` (comments + key order
+ * preserved) and edit only keys that actually changed. Untouched keys and
+ * their comments stay byte-stable. Falls back to plain stringify when there
+ * is no existing document yet.
+ */
+export declare function serializeManifest(manifest: Manifest, existingContent?: string | null): string;
 /** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export declare function readManifest(repoPath: string): Manifest | null;
 /** Write a Manifest object to agents.yaml in the given directory. */

package/dist/lib/manifest.js

@@ -16,9 +16,48 @@ const manifestLockDepth = new Map();
 export function parseManifest(content) {
     return yaml.parse(content);
 }
-/** Serialize a Manifest object to a YAML string with 2-space indentation. */
-export function serializeManifest(manifest) {
-    return yaml.stringify(manifest, { indent: 2 });
+/**
+ * Serialize a Manifest to YAML WITHOUT destroying hand-written comments.
+ *
+ * Plain `yaml.stringify(manifest)` drops every comment, so `agents mcp add`
+ * (and every other writeManifest caller) used to clobber annotations in
+ * agents.yaml. Matching `serializeCentral` in state.ts: when existing file
+ * text is provided, parse it into a `yaml.Document` (comments + key order
+ * preserved) and edit only keys that actually changed. Untouched keys and
+ * their comments stay byte-stable. Falls back to plain stringify when there
+ * is no existing document yet.
+ */
+export function serializeManifest(manifest, existingContent) {
+    const entries = Object.entries(manifest).filter(([, v]) => v !== undefined);
+    const isEmpty = entries.length === 0;
+    if (existingContent == null || existingContent.trim() === '') {
+        return isEmpty ? '' : yaml.stringify(manifest, { indent: 2 });
+    }
+    const doc = yaml.parseDocument(existingContent);
+    const current = doc.toJSON() ?? {};
+    let changed = false;
+    for (const [k, v] of entries) {
+        if (JSON.stringify(current[k]) !== JSON.stringify(v)) {
+            doc.set(k, v);
+            changed = true;
+        }
+    }
+    // Full-document write: callers do read-modify-write, so keys absent from the
+    // new manifest are intentional removals (e.g. clearing beta).
+    for (const k of Object.keys(current)) {
+        const next = manifest[k];
+        if (!(k in manifest) || next === undefined) {
+            doc.delete(k);
+            changed = true;
+        }
+    }
+    // Nothing changed → keep the file byte-identical (comments intact).
+    if (!changed)
+        return existingContent;
+    // Force BLOCK style: an existing flow root (e.g. legacy `{}`) would otherwise
+    // make edited nodes render flow. collectionStyle pins the whole doc block
+    // while parseDocument still preserves comments + key ordering.
+    return isEmpty ? '' : doc.toString({ collectionStyle: 'block' });
 }
 /** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export function readManifest(repoPath) {
@@ -55,8 +94,24 @@ function withManifestLock(filePath, fn) {
 /** Write a Manifest object to agents.yaml in the given directory. */
 export function writeManifest(repoPath, manifest) {
     const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
-    const content = serializeManifest(manifest);
-    withManifestLock(manifestPath, () => atomicWriteFileSync(manifestPath, content));
+    withManifestLock(manifestPath, () => {
+        let existing = null;
+        try {
+            existing = fs.readFileSync(manifestPath, 'utf-8');
+        }
+        catch {
+            /* first write — no file yet (or empty lock target) */
+        }
+        // ensureLockTarget may have created an empty file for the lock path.
+        if (existing !== null && existing.trim() === '')
+            existing = null;
+        const content = serializeManifest(manifest, existing);
+        // Skip the atomic rewrite when nothing changed so comments stay byte-stable
+        // and concurrent readers never see a no-op churn.
+        if (existing !== null && content === existing)
+            return;
+        atomicWriteFileSync(manifestPath, content);
+    });
 }
 /** Create a Manifest with sensible defaults for a fresh agents repo. */
 export function createDefaultManifest() {

package/dist/lib/mcp.js

@@ -596,6 +596,7 @@ function writeMcpConfigSupportsAgent(agentId) {
         case 'hermes':
         case 'pi':
         case 'muse':
+        case 'warp':
             return true;
         default:
             return false;
@@ -621,7 +622,10 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
         // omp reads the same Claude `{ "mcpServers": {...} }` schema from .mcp.json
         // (stdio: command/args/env; http/sse: url/headers — transport inferred from
         // command/url presence).
-        case 'pi': {
+        case 'pi':
+        // Oz reads the same Claude `{ "mcpServers": {...} }` schema from
+        // `.warp/.mcp.json` (stdio + http with headers).
+        case 'warp': {
             let config = {};
             if (fs.existsSync(configPath)) {
                 try {

package/dist/lib/menubar/MenubarHelper.app/Contents/Info.plist

@@ -7,7 +7,11 @@
     <key>CFBundleIdentifier</key>
     <string>com.phnx-labs.agents-menubar</string>
     <key>CFBundleName</key>
-    <string>Agents Menu Bar</string>
+    <string>AGI Menu</string>
+    <key>CFBundleDisplayName</key>
+    <string>AGI Menu</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>

package/dist/lib/menubar/MenubarHelper.app/Contents/_CodeSignature/CodeResources

@@ -3,9 +3,22 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		jOjZVimcFRHoP2VPzgn8uM8mjkA=
+		</data>
+	</dict>
 	<key>files2</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			GFvSLeNYJ3ASxW3OzcuiB4aID0gZUBkpozmWZkbTFNw=
+			</data>
+		</dict>
+	</dict>
 	<key>rules</key>
 	<dict>
 		<key>^Resources/</key>

package/dist/lib/menubar/install-menubar.d.ts

@@ -111,6 +111,54 @@ export declare function menubarPlistNeedsRepoint(opts: {
  * upgrade migration won't re-enable it.
  */
 export declare function disableMenubarService(): void;
+/**
+ * Which install is allowed to (re)install the shared helper.
+ *
+ * The helper lives at ONE path in Application Support, but any number of
+ * agents-cli copies can be present on a box and every one of them runs the
+ * startup self-heal. The version stamp and the plist's baked `AGENTS_ENTRY` each
+ * record whichever copy acted last, so without an ownership rule every copy
+ * reads the others' marks as drift and recopies the bundle over them. Recopying
+ * replaces the executable under the live helper and kills it; launchd
+ * `KeepAlive` restarts it; the next copy repeats it. Measured on one box: a new
+ * pid every 5-15s, 578 launches in the helper's log, a status item that never
+ * stayed visible, and `agents menubar status` still reporting `running: yes`
+ * because a pid always existed (#2109).
+ *
+ * There is deliberately NO content comparison here. Comparing the shipped helper
+ * against the installed one cannot distinguish "real upgrade" from "another
+ * install's copy": the helper is rebuilt, re-signed and re-notarized on every
+ * release (`menubar/scripts/build.sh` via `release.sh`), so consecutive releases
+ * ship byte-different bundles from identical Swift source — 1.22.20/21/22 all
+ * have the same 2876288-byte executable and three different sha256s AND three
+ * different CDHashes. Any digest gate therefore reports "changed" for exactly
+ * the skew case it was meant to exempt.
+ *
+ * So ownership decides instead: the plist's `AGENTS_ENTRY` names the owner, and
+ * only the owner may reinstall. A non-owner takes over only once the recorded
+ * owner is gone from disk, which is what makes the rule converge — a dead
+ * install cannot hold the helper hostage, and a live one cannot be fought over.
+ * A same-install upgrade keeps its entry path, so `npm update` still installs
+ * the new helper normally. Pure so the truth table is unit-testable.
+ */
+export declare function mayInstallMenubarHelper(opts: {
+    /** `AGENTS_ENTRY` baked into the installed plist — the recorded owner. */
+    plistEntry: string | null;
+    /** `resolveCliEntry()` for the install now running `agents`. */
+    activeEntry: string | null;
+    /** Whether `plistEntry` still exists on disk. */
+    ownerEntryExists: boolean;
+    /** The App Support helper executable is absent — a repair, not a contest. */
+    helperExecMissing: boolean;
+    /** Installed copy is ad-hoc while the shipped source is Developer ID. */
+    needsDevIdHeal: boolean;
+    /** ms since the last self-heal reinstall, or null if none is recorded. */
+    msSinceLastHeal: number | null;
+    /** How long a non-owner waits before it may take over. */
+    cooldownMs: number;
+    /** This install's OWN shipped bundle is Developer-ID signed (not ad-hoc/dev). */
+    sourceIsDeveloperId: boolean;
+}): boolean;
 /**
  * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
  * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
@@ -121,8 +169,10 @@ export declare function disableMenubarService(): void;
  *
  * Without the staleness re-enable, `npm update` refreshed the CLI but left the
  * menu bar running the previous release's helper binary on a possibly-stale
- * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
- * Best-effort — never throws into startup.
+ * plist. Everything past the ownership gate is unchanged; the gate is what stops
+ * coexisting installs reinstalling over each other forever (#2109). No-ops if:
+ * not darwin, the user opted out, or no helper bundle ships. Best-effort — never
+ * throws into startup.
  */
 export declare function installMenubarLaunchAgentOnUpgrade(): void;
 /** One step of `agents menubar setup`, and how it came out. */

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

@@ -468,6 +468,115 @@ export function disableMenubarService() {
     }
     catch { /* best effort */ }
 }
+/**
+ * Which install is allowed to (re)install the shared helper.
+ *
+ * The helper lives at ONE path in Application Support, but any number of
+ * agents-cli copies can be present on a box and every one of them runs the
+ * startup self-heal. The version stamp and the plist's baked `AGENTS_ENTRY` each
+ * record whichever copy acted last, so without an ownership rule every copy
+ * reads the others' marks as drift and recopies the bundle over them. Recopying
+ * replaces the executable under the live helper and kills it; launchd
+ * `KeepAlive` restarts it; the next copy repeats it. Measured on one box: a new
+ * pid every 5-15s, 578 launches in the helper's log, a status item that never
+ * stayed visible, and `agents menubar status` still reporting `running: yes`
+ * because a pid always existed (#2109).
+ *
+ * There is deliberately NO content comparison here. Comparing the shipped helper
+ * against the installed one cannot distinguish "real upgrade" from "another
+ * install's copy": the helper is rebuilt, re-signed and re-notarized on every
+ * release (`menubar/scripts/build.sh` via `release.sh`), so consecutive releases
+ * ship byte-different bundles from identical Swift source — 1.22.20/21/22 all
+ * have the same 2876288-byte executable and three different sha256s AND three
+ * different CDHashes. Any digest gate therefore reports "changed" for exactly
+ * the skew case it was meant to exempt.
+ *
+ * So ownership decides instead: the plist's `AGENTS_ENTRY` names the owner, and
+ * only the owner may reinstall. A non-owner takes over only once the recorded
+ * owner is gone from disk, which is what makes the rule converge — a dead
+ * install cannot hold the helper hostage, and a live one cannot be fought over.
+ * A same-install upgrade keeps its entry path, so `npm update` still installs
+ * the new helper normally. Pure so the truth table is unit-testable.
+ */
+export function mayInstallMenubarHelper(opts) {
+    // Repairs are never gated: a missing binary or a broken signing identity leaves
+    // the menu bar dead or re-prompting for Accessibility, and no other install can
+    // be "fighting" for a bundle that isn't there. Blocking these behind ownership
+    // is what turned the first version of this gate into a silent stuck state.
+    if (opts.helperExecMissing || opts.needsDevIdHeal)
+        return true;
+    // Can't resolve which install we are (a dev/tsx run) — never churn the plist.
+    if (!opts.activeEntry)
+        return false;
+    // No owner recorded yet (fresh or pre-`AGENTS_ENTRY` plist) — adopt it.
+    if (!opts.plistEntry)
+        return true;
+    if (opts.plistEntry === opts.activeEntry)
+        return true; // we are the owner
+    if (!opts.ownerEntryExists)
+        return true; // the recorded owner is gone
+    // A foreign install while the owner still exists. Refusing outright bounds the
+    // loop but strands the user when the recorded owner is a stale copy that simply
+    // still sits on disk (an old nvm node dir) while their daily driver upgrades:
+    // that install would never heal again. So it may take over, but only once per
+    // cooldown — which turns an every-invocation storm into at most one restart per
+    // cooldown while keeping every install able to make progress.
+    //
+    // Except an ad-hoc/dev-signed copy, which never seizes a healthy helper on a
+    // timer. `scripts/install.sh` deliberately puts a dev build beside the npm
+    // global, and its bundle cannot be notarized; letting it win the timed takeover
+    // would recopy an ad-hoc bundle over a good Developer-ID one, and Gatekeeper
+    // then rejects the result as "damaged" and AppKit crashes at launch (RUSH-2134)
+    // — trading a cosmetic loop for a broken menu bar. It can still take over when
+    // the owner is genuinely gone (above), which is the case that must not deadlock.
+    if (!opts.sourceIsDeveloperId)
+        return false;
+    return opts.msSinceLastHeal === null || opts.msSinceLastHeal >= opts.cooldownMs;
+}
+/**
+ * How long a non-owner install waits before it may take the helper over. Long
+ * enough that a multi-install box restarts the helper at most once an hour
+ * instead of every few seconds; short enough that a user who switched installs
+ * gets their upgrade without hunting for `agents menubar setup`.
+ */
+const MENUBAR_TAKEOVER_COOLDOWN_MS = 60 * 60 * 1000;
+/** Timestamp of the last self-heal reinstall, next to the version stamp. */
+function lastHealMarkerPath() {
+    return path.join(installDir(), '.menubar-last-heal');
+}
+function msSinceLastMenubarHeal() {
+    try {
+        const t = Number(fs.readFileSync(lastHealMarkerPath(), 'utf-8').trim());
+        if (!Number.isFinite(t))
+            return null;
+        return Math.max(0, Date.now() - t);
+    }
+    catch {
+        return null;
+    }
+}
+function stampMenubarHeal() {
+    try {
+        fs.mkdirSync(installDir(), { recursive: true });
+        fs.writeFileSync(lastHealMarkerPath(), String(Date.now()));
+    }
+    catch { /* best effort */ }
+}
+/** Whether this install may (re)install the helper (see `mayInstallMenubarHelper`). */
+function mayHealMenubar(needsDevIdHeal) {
+    const plistEntry = readPlistEnvValue('AGENTS_ENTRY');
+    const src = sourceAppPath();
+    return mayInstallMenubarHelper({
+        plistEntry,
+        activeEntry: resolveCliEntry(),
+        ownerEntryExists: Boolean(plistEntry) && fs.existsSync(plistEntry),
+        helperExecMissing: !fs.existsSync(installedExecutablePath()),
+        needsDevIdHeal,
+        msSinceLastHeal: msSinceLastMenubarHeal(),
+        cooldownMs: MENUBAR_TAKEOVER_COOLDOWN_MS,
+        sourceIsDeveloperId: Boolean(src) && hasDeveloperIdSignature(src),
+    });
+}
 /**
  * Startup self-heal, run on every darwin CLI invocation (see src/index.ts).
  * No-ops cheaply (a couple of existsSync + a tiny file read) unless work is
@@ -478,8 +587,10 @@ export function disableMenubarService() {
  *
  * Without the staleness re-enable, `npm update` refreshed the CLI but left the
  * menu bar running the previous release's helper binary on a possibly-stale
- * plist. No-ops if: not darwin, the user opted out, or no helper bundle ships.
- * Best-effort — never throws into startup.
+ * plist. Everything past the ownership gate is unchanged; the gate is what stops
+ * coexisting installs reinstalling over each other forever (#2109). No-ops if:
+ * not darwin, the user opted out, or no helper bundle ships. Best-effort — never
+ * throws into startup.
  */
 export function installMenubarLaunchAgentOnUpgrade() {
     try {
@@ -495,12 +606,23 @@ export function installMenubarLaunchAgentOnUpgrade() {
         }
         // Re-enable (recopy helper + rewrite plist) when the version drifted OR the
         // plist's baked interpreter/entry no longer point at the install now running
-        // `agents` — the dual-install skew a version bump alone can't catch — OR the
+        // `agents` — e.g. the owner moved between node interpreters — OR the
         // installed copy is still ad-hoc while the shipped source is Developer ID
         // (older heal path; Accessibility re-prompts until the identity is restored).
-        if (menubarSetupStale() || menubarSetupNeedsRepoint() || installedNeedsDevIdHeal()) {
-            enableMenubarService({ clearOptOut: false });
-        }
+        const needsDevIdHeal = installedNeedsDevIdHeal();
+        if (!(menubarSetupStale() || menubarSetupNeedsRepoint() || needsDevIdHeal))
+            return;
+        // ...but a copy that does not own the helper only gets to act on that drift
+        // once per cooldown. Without the gate every coexisting install recopies the
+        // bundle on every invocation, killing the live helper on a loop (#2109).
+        if (!mayHealMenubar(needsDevIdHeal))
+            return;
+        // Stamp only a heal that actually happened. `enableMenubarService` returns
+        // false without installing when the bundle fails the Gatekeeper check, and
+        // stamping first would spend the shared cooldown on a no-op — locking every
+        // non-owner out for another hour while nothing had been fixed.
+        if (enableMenubarService({ clearOptOut: false }))
+            stampMenubarHeal();
     }
     catch {
         /* never block startup on the menu bar */

package/dist/lib/menubar/snapshot.d.ts

@@ -0,0 +1,15 @@
+import type { WatchdogTickResult } from '../watchdog/runner.js';
+export interface MenubarSnapshot {
+    version: 1;
+    capturedAt: string;
+    routines: Record<string, unknown>[];
+    recentSessions: Record<string, unknown>[];
+    activeSessions: Record<string, unknown>[];
+    watchdog: {
+        enabled: boolean;
+        lastTick: Pick<WatchdogTickResult, 'didNudge' | 'counts'> | null;
+    };
+}
+export declare function readLastWatchdogTick(stateDir?: string): WatchdogTickResult | null;
+/** One-process read model for AGI Menu's repeating three-minute refresh. */
+export declare function computeMenubarSnapshot(): Promise<MenubarSnapshot>;

package/dist/lib/menubar/snapshot.js

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildRoutineListJson } from '../../commands/routines.js';
+import { backfillActiveRowsFromIndex, serializeActiveSessionsForJson, serializeSessionsJson } from '../../commands/sessions.js';
+import { getConfigValue } from '../device-config.js';
+import { querySessions } from '../session/db.js';
+import { readActiveSessionsCache } from '../session/session-cache.js';
+import { getRuntimeStateDir } from '../state.js';
+export function readLastWatchdogTick(stateDir = path.join(getRuntimeStateDir(), 'watchdog')) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, 'last-tick.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** One-process read model for AGI Menu's repeating three-minute refresh. */
+export async function computeMenubarSnapshot() {
+    const [routines, recent] = await Promise.all([
+        Promise.resolve(buildRoutineListJson()),
+        Promise.resolve(querySessions({ limit: 40, skipExistenceCheck: true })),
+    ]);
+    const active = readActiveSessionsCache('local');
+    const activeSessions = active?.sessions ?? [];
+    backfillActiveRowsFromIndex(activeSessions);
+    return {
+        version: 1,
+        capturedAt: new Date().toISOString(),
+        routines,
+        recentSessions: JSON.parse(serializeSessionsJson(recent)),
+        activeSessions: serializeActiveSessionsForJson(activeSessions),
+        watchdog: {
+            enabled: getConfigValue('watchdog.enabled').value === true,
+            lastTick: (() => {
+                const tick = readLastWatchdogTick();
+                return tick ? { didNudge: tick.didNudge, counts: tick.counts } : null;
+            })(),
+        },
+    };
+}

package/dist/lib/plugins.js

@@ -68,8 +68,20 @@ export function discoverPluginsInDir(pluginsDir, spec = { kind: 'user' }) {
             continue;
         const pluginRoot = path.join(pluginsDir, entry.name);
         const manifest = loadPluginManifest(pluginRoot);
-        if (!manifest)
+        if (!manifest) {
+            // A directory that looks like a plugin root but has no valid manifest is
+            // silently invisible to every downstream command (list/info/sync, and the
+            // materialize-into-version-homes copy) with no other diagnostic anywhere
+            // in the chain — it can sit here indefinitely, on the correct git commit,
+            // and never surface as broken (RUSH-2270: the `work` plugin shipped
+            // without .claude-plugin/plugin.json and nothing noticed for a full merge
+            // cycle). Warn once here, at the one place that decides discoverability,
+            // so the gap is visible the moment `agents sync` runs.
+            const manifestPath = path.join(entry.name, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
+            process.stderr.write(`agents-cli: '${entry.name}' in ${pluginsDir} has no valid ${manifestPath} ` +
+                `(missing, malformed JSON, or missing name/version) — skipped, not discovered as a plugin.\n`);
             continue;
+        }
         plugins.push(buildDiscoveredPlugin(pluginRoot, manifest, spec));
     }
     return plugins;

package/dist/lib/refresh.d.ts

@@ -17,6 +17,11 @@ export interface RefreshOptions {
     skipPrompts?: boolean;
     /** Skip CLI version install/upgrade from agents.yaml. */
     skipClis?: boolean;
+    /**
+     * Suppress human progress lines on stdout. Required for machine consumers
+     * (`agents sync --json` / fleet fan-out) so stdout stays a single JSON object.
+     */
+    quiet?: boolean;
 }
 /**
  * Re-materialize local state from declared configuration: install CLI versions,