@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/lib/hooks/cache.js

@@ -463,6 +463,9 @@ except Exception: pass' 2>/dev/null || true)"
     ;;
 esac
 CACHE_FILE="$CACHE_DIR/$HOOK_NAME$cache_suffix.out"
+# Failure sentinel: touched on bg-refresh failure; mtime drives the backoff window.
+FAIL_FILE="$CACHE_FILE.fail"
+BACKOFF_SEC=60
 
 # Monotonic-ish nanosecond timer (macOS \`date\` has no %N).
 now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
@@ -491,9 +494,38 @@ if [ "$CACHE_STATUS" = miss ]; then
     # Stale-while-revalidate: serve stale immediately, refresh in detached child.
     cat "$CACHE_FILE"
     CACHE_STATUS=stale-prefetch
-    tmp="$CACHE_FILE.new.$$"
-    ( printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null && mv -f "$tmp" "$CACHE_FILE" || rm -f "$tmp" ) >/dev/null 2>&1 &
-    disown 2>/dev/null || true
+    # Fix 2: backoff — skip bg refresh if last attempt failed within BACKOFF_SEC.
+    _in_backoff=0
+    if [ -f "$FAIL_FILE" ]; then
+      _fail_mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$FAIL_FILE" 2>/dev/null || echo 0)
+      _now_s=$(date +%s)
+      _fail_age=$((_now_s - \${_fail_mtime:-0}))
+      [ "$_fail_age" -lt "$BACKOFF_SEC" ] && _in_backoff=1
+    fi
+    if [ "$_in_backoff" -eq 0 ]; then
+      # Fix 1: lockdir — only one background refresh runs at a time.
+      LOCK_DIR="$CACHE_FILE.bg.lck"
+      if mkdir "$LOCK_DIR" 2>/dev/null; then
+        tmp="$CACHE_FILE.new.$$"
+        # Fix 3: background subshell captures and logs its own real exit code.
+        (
+          trap 'rm -rf "$LOCK_DIR"' EXIT
+          _bg_exit=0
+          if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE" >"$tmp" 2>/dev/null; then
+            mv -f "$tmp" "$CACHE_FILE" && rm -f "$FAIL_FILE"
+          else
+            _bg_exit=$?
+            rm -f "$tmp"
+            touch "$FAIL_FILE"
+          fi
+          _bg_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          _bg_log_file="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+          printf '{"ts":"%s","event":"hook.cache.refresh","hook":"%s","cache":"bg-refresh","exit":%d}\\n' \\
+            "$_bg_ts" "$HOOK_NAME" "$_bg_exit" >>"$_bg_log_file" 2>/dev/null || true
+        ) >/dev/null 2>&1 &
+        disown 2>/dev/null || true
+      fi
+    fi
   else
     # Synchronous fetch + cache.
     tmp="$CACHE_FILE.new.$$"
@@ -501,6 +533,7 @@ if [ "$CACHE_STATUS" = miss ]; then
       EXIT=0
       cat "$tmp"
       mv -f "$tmp" "$CACHE_FILE"
+      rm -f "$FAIL_FILE"
     else
       EXIT=$?
       rm -f "$tmp"

package/dist/lib/hooks.d.ts

@@ -73,6 +73,14 @@ export declare function hookExists(agentId: AgentId, hookName: string): boolean;
  * Compares both script file and data file (if present).
  */
 export declare function hookContentMatches(agentId: AgentId, hookName: string, sourceEntry: HookEntry): boolean;
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export declare function getHooksDirInHome(agentId: AgentId, home: string): string;
 export declare function listInstalledHooksWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledHook[];
@@ -99,7 +107,7 @@ export interface HookWiringIssue {
      *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
      *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
     matcher: string;
-    /** The command settings.json should reference for this hook under `event`. */
+    /** The command the harness-native config should reference under `event`. */
     command: string;
 }
 export interface HookWiringReport {
@@ -109,18 +117,22 @@ export interface HookWiringReport {
     settingsPath?: string;
     /** Number of hooks the manifest says should be wired for this version. */
     expected?: number;
-    /** settings.json does not exist — nothing declared can be wired. */
+    /** Native hook config does not exist — nothing declared can be wired. */
     settingsMissing?: boolean;
-    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    /** Native hook config cannot be parsed — wiring can't be verified. */
     settingsUnparseable?: boolean;
     /** Hooks whose file is present/resolvable but that are NOT referenced in the
-     *  event array settings.json should carry them in. */
+     *  native event group/entry should carry them in. */
     unwired: HookWiringIssue[];
+    /** Expected hooks that ARE referenced in native config (expected − unwired).
+     *  Empty whenever wiring cannot be verified (unsupported family, missing or
+     *  unparseable settings). */
+    wired: HookWiringIssue[];
 }
 /**
- * Verify that every hook the manifest says should be wired for a (claude|droid)
- * version is actually REFERENCED in that version's native settings.json — not
- * merely present as a file on disk.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, not merely present as a
+ * file on disk.
  *
  * `agents doctor` compares hook FILES against source (see diffHooks in
  * doctor-diff.ts) but never checks the wiring, so a hook whose script is

package/dist/lib/hooks.js

@@ -673,6 +673,20 @@ export function hookContentMatches(agentId, hookName, sourceEntry) {
         return false;
     }
 }
+/**
+ * Hooks dir for an agent under an arbitrary home (version home or effective
+ * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
+ * kimi) must be translated to config-dir-relative first — a raw `path.join`
+ * would embed the absolute path as a relative segment and produce a hybrid
+ * path that never exists (RUSH-2237).
+ */
+export function getHooksDirInHome(agentId, home) {
+    const config = AGENTS[agentId];
+    const hooksDir = path.isAbsolute(config.hooksDir)
+        ? path.relative(config.configDir, config.hooksDir)
+        : config.hooksDir;
+    return path.join(home, agentConfigDirName(agentId), hooksDir);
+}
 export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), options) {
     const agent = AGENTS[agentId];
     if (!agent.supportsHooks) {
@@ -702,7 +716,7 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
     }
     // User-scoped hooks (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userDir = path.join(home, agentConfigDirName(agentId), agent.hooksDir);
+    const userDir = getHooksDirInHome(agentId, home);
     const userHooks = listHookEntriesFromDir(userDir);
     for (const hook of userHooks) {
         addHook(hook, 'user', agentId);
@@ -740,8 +754,7 @@ export async function installHooks(source, agents, options = {}) {
  * Path to the hooks dir of a specific version home (not the active one).
  */
 export function getVersionHooksDir(agent, version) {
-    const home = getVersionHomePath(agent, version);
-    return path.join(home, agentConfigDirName(agent), AGENTS[agent].hooksDir);
+    return getHooksDirInHome(agent, getVersionHomePath(agent, version));
 }
 /**
  * List hook entries in a specific version home.
@@ -749,20 +762,20 @@ export function getVersionHooksDir(agent, version) {
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
-// ─── wiring inspection (settings.json family: claude, droid) ──────────────────
+// ─── wiring inspection ────────────────────────────────────────────────────────
 /**
- * Agents whose hooks register through {@link registerHooksForClaude} — a native
- * settings.json shaped `hooks[event] = [{ matcher, hooks: [{ command }] }]`, with
- * no event renaming. These are the only agents this read-only wiring inspector
- * understands; every other harness uses a divergent config format and/or event
- * map (Gemini/Antigravity settings.json variants, Codex config.toml, the OpenCode
- * plugin, …), so it reports them unsupported rather than risk a false verdict.
+ * Native hook-config families understood by this read-only inspector. Claude,
+ * Droid, and Muse share settings.json; Grok uses the same grouped event shape
+ * in hooks/hooks.json; Kimi stores one hook per [[hooks]] config.toml table.
+ * Other harnesses report unsupported rather than risk a false verdict.
  */
-const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid'];
+const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
+const HOOKS_JSON_HOOK_FAMILY = ['grok'];
+const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
 /**
- * Verify that every hook the manifest says should be wired for a (claude|droid)
- * version is actually REFERENCED in that version's native settings.json — not
- * merely present as a file on disk.
+ * Verify that every hook the manifest says should be wired is actually
+ * referenced in that version's harness-native config, not merely present as a
+ * file on disk.
  *
  * `agents doctor` compares hook FILES against source (see diffHooks in
  * doctor-diff.ts) but never checks the wiring, so a hook whose script is
@@ -774,11 +787,18 @@ const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid'];
  * resolveHookCommand performs, so it never mutates the version home.
  */
 export function checkVersionHookWiring(agent, version) {
-    if (!AGENTS[agent].supportsHooks || !SETTINGS_JSON_HOOK_FAMILY.includes(agent)) {
-        return { supported: false, unwired: [] };
+    if (!AGENTS[agent].supportsHooks ||
+        (!SETTINGS_JSON_HOOK_FAMILY.includes(agent) &&
+            !HOOKS_JSON_HOOK_FAMILY.includes(agent) &&
+            !TOML_ARRAY_HOOK_FAMILY.includes(agent))) {
+        return { supported: false, unwired: [], wired: [] };
     }
     const versionHome = getVersionHomePath(agent, version);
-    const settingsPath = path.join(versionHome, agentConfigDirName(agent), 'settings.json');
+    const settingsPath = HOOKS_JSON_HOOK_FAMILY.includes(agent)
+        ? path.join(versionHome, '.grok', 'hooks', 'hooks.json')
+        : TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? path.join(versionHome, '.kimi-code', 'config.toml')
+            : path.join(versionHome, agentConfigDirName(agent), 'settings.json');
     const localHooksDir = getVersionHooksDir(agent, version);
     // Resolve ONLY to a script that was actually synced for THIS agent+version: the
     // copy in the version home hooks dir, or an absolute subrule-dir path (those are
@@ -815,11 +835,17 @@ export function checkVersionHookWiring(agent, version) {
         const command = expectedCommand(name, hookDef);
         if (!command)
             continue; // script unresolved — a file gap, reported by diffHooks
-        // Mirror registerHooksForClaude: a hook registers under the matcher group
-        // `hookDef.matcher || ''` for each of its events.
-        const matcher = hookDef.matcher || '';
-        for (const event of hookDef.events)
-            expected.push({ name, event, matcher, command });
+        for (const event of hookDef.events) {
+            if (HOOKS_JSON_HOOK_FAMILY.includes(agent)) {
+                const matcher = GROK_MATCHER_EVENTS.has(event)
+                    ? (GROK_MATCHER_ALIASES[hookDef.matcher || ''] ?? hookDef.matcher ?? '')
+                    : '';
+                expected.push({ name, event, matcher, command });
+            }
+            else {
+                expected.push({ name, event, matcher: hookDef.matcher || '', command });
+            }
+        }
     }
     if (!fs.existsSync(settingsPath)) {
         return {
@@ -828,11 +854,15 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsMissing: expected.length > 0,
             unwired: [],
+            wired: [],
         };
     }
     let config;
     try {
-        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const raw = fs.readFileSync(settingsPath, 'utf-8');
+        config = TOML_ARRAY_HOOK_FAMILY.includes(agent)
+            ? TOML.parse(raw)
+            : JSON.parse(raw);
     }
     catch {
         return {
@@ -841,6 +871,7 @@ export function checkVersionHookWiring(agent, version) {
             expected: expected.length,
             settingsUnparseable: true,
             unwired: [],
+            wired: [],
         };
     }
     // Command strings actually referenced, keyed by (event, matcher) — a hook wired
@@ -848,30 +879,49 @@ export function checkVersionHookWiring(agent, version) {
     // not just by event.
     const wiredByGroup = new Map();
     const groupKey = (event, matcher) => `${event}\n${matcher}`;
-    const hooks = config.hooks && typeof config.hooks === 'object'
-        ? config.hooks
-        : {};
-    for (const [event, groups] of Object.entries(hooks)) {
-        if (!Array.isArray(groups))
-            continue;
-        for (const group of groups) {
-            if (!group || !Array.isArray(group.hooks))
+    if (TOML_ARRAY_HOOK_FAMILY.includes(agent)) {
+        const hooks = Array.isArray(config.hooks) ? config.hooks : [];
+        for (const hook of hooks) {
+            if (typeof hook.event !== 'string' || typeof hook.command !== 'string')
                 continue;
-            const matcher = typeof group.matcher === 'string' ? group.matcher : '';
-            const key = groupKey(event, matcher);
+            const matcher = typeof hook.matcher === 'string' ? hook.matcher : '';
+            const key = groupKey(hook.event, matcher);
             let cmds = wiredByGroup.get(key);
             if (!cmds) {
                 cmds = new Set();
                 wiredByGroup.set(key, cmds);
             }
-            for (const h of group.hooks) {
-                if (h && typeof h.command === 'string')
-                    cmds.add(h.command);
+            cmds.add(hook.command);
+        }
+    }
+    else {
+        const hooks = config.hooks && typeof config.hooks === 'object'
+            ? config.hooks
+            : {};
+        for (const [event, groups] of Object.entries(hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            for (const group of groups) {
+                if (!group || !Array.isArray(group.hooks))
+                    continue;
+                const matcher = typeof group.matcher === 'string' ? group.matcher : '';
+                const key = groupKey(event, matcher);
+                let cmds = wiredByGroup.get(key);
+                if (!cmds) {
+                    cmds = new Set();
+                    wiredByGroup.set(key, cmds);
+                }
+                for (const h of group.hooks) {
+                    if (h && typeof h.command === 'string')
+                        cmds.add(h.command);
+                }
             }
         }
     }
-    const unwired = expected.filter((e) => !wiredByGroup.get(groupKey(e.event, e.matcher))?.has(e.command));
-    return { supported: true, settingsPath, expected: expected.length, unwired };
+    const isWired = (entry) => wiredByGroup.get(groupKey(entry.event, entry.matcher))?.has(entry.command) ?? false;
+    const unwired = expected.filter((entry) => !isWired(entry));
+    const wired = expected.filter(isWired);
+    return { supported: true, settingsPath, expected: expected.length, unwired, wired };
 }
 /**
  * Check if a hook installed in a specific version matches central content.
@@ -1402,7 +1452,7 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     // Scripts are copied into the version home during sync — prefer that stable
     // local path so registered commands don't break when source dirs change.
     const localHooksDir = !overrideRoots
-        ? path.join(versionHome, agentConfigDirName(agentId), AGENTS[agentId].hooksDir)
+        ? getHooksDirInHome(agentId, versionHome)
         : null;
     const resolveScript = (script) => {
         // Subrule-dir hooks declare an already-absolute script path. Use it
@@ -1453,6 +1503,12 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         // registrar targeting `.factory/settings.json` (agentConfigDirName('droid')).
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, agentConfigDirName('droid'));
     }
+    if (agentId === 'muse') {
+        // Muse Code: Claude-compatible hooks block in ~/.config/muse/settings.json
+        // (events SessionStart / PreToolUse / …, matcher groups, command hooks).
+        // settings.json MUST carry schema_version: 1 or Muse refuses to start.
+        return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, agentConfigDirName('muse'), { schemaVersion: 1 });
+    }
     if (agentId === 'codex') {
         return registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -1675,7 +1731,7 @@ const ANTIGRAVITY_EVENT_MAP = {
     Stop: 'on_loop_stop',
     OnError: 'on_error',
 };
-function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, configDirName = '.claude') {
+function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, configDirName = '.claude', options) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, configDirName);
@@ -1692,6 +1748,10 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
             return { registered, errors };
         }
     }
+    // Muse (and any future agent that pins a settings schema) requires this key.
+    if (options?.schemaVersion !== undefined && config.schema_version === undefined) {
+        config.schema_version = options.schemaVersion;
+    }
     if (!config.hooks || typeof config.hooks !== 'object') {
         config.hooks = {};
     }

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

@@ -595,6 +595,7 @@ function writeMcpConfigSupportsAgent(agentId) {
         case 'opencode':
         case 'hermes':
         case 'pi':
+        case 'muse':
             return true;
         default:
             return false;
@@ -797,6 +798,49 @@ export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite')
             fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
             break;
         }
+        case 'muse': {
+            // Muse Code settings.json: requires schema_version: 1; MCP lives under
+            // mcp_servers with an explicit transport (stdio | streamable_http).
+            // See https://dev.meta.ai/docs/muse-code/extending#mcp
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            if (config.schema_version === undefined) {
+                config.schema_version = 1;
+            }
+            const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object' && !Array.isArray(config.mcp_servers)
+                ? { ...config.mcp_servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        transport: 'stdio',
+                        command: server.command,
+                        args: server.args || [],
+                        ...(server.env && Object.keys(server.env).length > 0 ? { env: server.env } : {}),
+                        enabled: true,
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        transport: 'streamable_http',
+                        url: server.url,
+                        ...(server.headers && Object.keys(server.headers).length > 0 ? { headers: server.headers } : {}),
+                        enabled: true,
+                    };
+                }
+            }
+            config.mcp_servers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
     }
 }
 /**

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. */