@phnx-labs/agents-cli 1.22.23 → 1.22.24

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/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/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,

package/dist/lib/refresh.js

@@ -29,7 +29,7 @@ import { isPromptCancelled } from '../commands/utils.js';
  * hook reads from a fixed path so it survives version upgrades. If the root
  * file doesn't exist yet but an agent-scoped one does, hoist the first one found.
  */
-function migratePromptcutsToRoot(agentsDir) {
+function migratePromptcutsToRoot(agentsDir, quiet = false) {
     const rootPath = path.join(agentsDir, 'promptcuts.yaml');
     if (fs.existsSync(rootPath))
         return;
@@ -39,7 +39,8 @@ function migratePromptcutsToRoot(agentsDir) {
         if (fs.existsSync(legacyPath)) {
             try {
                 fs.renameSync(legacyPath, rootPath);
-                console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
+                if (!quiet)
+                    console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
                 return;
             }
             catch {
@@ -56,16 +57,19 @@ function migratePromptcutsToRoot(agentsDir) {
  * Idempotent — safe to run repeatedly. No network operations.
  */
 export async function refresh(options = {}) {
-    const { agentFilter, skipPrompts = false, skipClis = false } = options;
+    const { agentFilter, skipPrompts = false, skipClis = false, quiet = false } = options;
     const agentsDir = getUserAgentsDir();
-    migratePromptcutsToRoot(agentsDir);
+    // Gate every human progress line so --json / fleet fan-out can parse stdout.
+    const log = (...args) => { if (!quiet)
+        console.log(...args); };
+    migratePromptcutsToRoot(agentsDir, quiet);
     const manifest = readManifest(agentsDir);
     if (!manifest) {
-        console.log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
+        log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
     }
     // 1. Install/upgrade CLI versions from agents.yaml
     if (!skipClis && manifest?.agents) {
-        console.log(chalk.bold('\nCLI Versions:\n'));
+        log(chalk.bold('\nCLI Versions:\n'));
         const cliAgents = Object.keys(manifest.agents);
         for (const agentId of cliAgents) {
             if (agentFilter && agentId !== agentFilter)
@@ -94,7 +98,7 @@ export async function refresh(options = {}) {
     }
     // 2. Register MCP servers
     if (manifest?.mcp && Object.keys(manifest.mcp).length > 0) {
-        console.log(chalk.bold('\nMCP Servers:\n'));
+        log(chalk.bold('\nMCP Servers:\n'));
         for (const [name, config] of Object.entries(manifest.mcp)) {
             if (!config.command || config.transport === 'http')
                 continue;
@@ -109,7 +113,7 @@ export async function refresh(options = {}) {
                     const label = result.version
                         ? `${agentLabel(result.agentId)}@${result.version}`
                         : agentLabel(result.agentId);
-                    console.log(`  ${chalk.green('+')} ${name} -> ${label}`);
+                    log(`  ${chalk.green('+')} ${name} -> ${label}`);
                 }
             }
         }
@@ -147,13 +151,13 @@ export async function refresh(options = {}) {
                 forceFullSync = true;
             }
             else if (!hasAnySynced) {
-                console.log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
+                log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
                 const userSelection = await promptResourceSelection(agentId);
                 if (userSelection)
                     selection = userSelection;
             }
             else if (hasNewResources(newResources, agentId, defaultVer)) {
-                console.log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
+                log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
                 const userSelection = await promptNewResourceSelection(agentId, newResources, defaultVer);
                 if (userSelection)
                     selection = userSelection;
@@ -184,13 +188,13 @@ export async function refresh(options = {}) {
                     const verNote = versionsToSync.length > 1
                         ? chalk.gray(` (${versionsToSync.length} versions)`)
                         : '';
-                    console.log(chalk.green(`  Synced: ${[...kinds].join(', ')}`) + verNote);
+                    log(chalk.green(`  Synced: ${[...kinds].join(', ')}`) + verNote);
                 }
             }
         }
         catch (err) {
             if (isPromptCancelled(err)) {
-                console.log(chalk.gray('Skipped resource selection'));
+                log(chalk.gray('Skipped resource selection'));
             }
             else {
                 throw err;
@@ -215,24 +219,24 @@ export async function refresh(options = {}) {
                 const result = registerHooksToSettings(agentId, home, hookManifest);
                 hookRegistered += result.registered.length;
                 for (const error of result.errors) {
-                    console.log(chalk.yellow(`  Hook warning: ${error}`));
+                    log(chalk.yellow(`  Hook warning: ${error}`));
                 }
             }
         }
         if (hookRegistered > 0) {
-            console.log(chalk.green(`\nRegistered ${hookRegistered} hook lifecycle event(s)`));
+            log(chalk.green(`\nRegistered ${hookRegistered} hook lifecycle event(s)`));
         }
     }
     // 5. Auto-add shims to PATH
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {
-            console.log(chalk.green(`\nAdded shims to ${pathResult.location}`));
-            console.log(chalk.gray(pathResult.reloadHint));
+            log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+            log(chalk.gray(pathResult.reloadHint));
         }
         else if (!pathResult.success) {
-            console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));
-            console.log(chalk.gray(getPathSetupInstructions()));
+            log(chalk.yellow('\nCould not auto-add shims to PATH:'));
+            log(chalk.gray(getPathSetupInstructions()));
         }
     }
     // 6. Prompt for missing default versions
@@ -273,63 +277,63 @@ export async function refresh(options = {}) {
             setGlobalDefault(agentId, version);
             const symlinkResult = await switchConfigSymlink(agentId, version);
             if (!symlinkResult.success) {
-                console.log(chalk.yellow(`Warning: ${symlinkResult.error}`));
+                log(chalk.yellow(`Warning: ${symlinkResult.error}`));
             }
             else if (symlinkResult.backupPath) {
-                console.log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
+                log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
             }
             switchHomeFileSymlinks(agentId, version);
-            console.log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
+            log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
         }
     }
     // 7. Install declared host-CLIs
     try {
         const { statuses, errors } = listCliStatus(process.cwd());
         for (const err of errors) {
-            console.log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
+            log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
         }
         const missing = statuses.filter((s) => !s.installed);
         if (missing.length > 0) {
-            console.log(chalk.bold('\nDeclared CLIs missing from this host:'));
+            log(chalk.bold('\nDeclared CLIs missing from this host:'));
             for (const s of missing) {
                 const method = selectInstallMethod(s.manifest);
                 const action = method ? describeMethod(method) : chalk.red('no compatible install method');
-                console.log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+                log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
             }
-            console.log('');
+            log('');
             if (!skipPrompts) {
                 const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
                 if (proceed) {
                     for (const s of missing) {
-                        console.log(chalk.bold(`\n→ ${s.manifest.name}`));
+                        log(chalk.bold(`\n→ ${s.manifest.name}`));
                         const result = installCli(s.manifest);
                         if (result.error) {
-                            console.log(chalk.red(`  ${result.error}`));
+                            log(chalk.red(`  ${result.error}`));
                             continue;
                         }
                         if (result.installed) {
-                            console.log(chalk.green(`  installed`));
+                            log(chalk.green(`  installed`));
                             if (s.manifest.postInstall) {
-                                console.log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                                log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
                             }
                         }
                         else {
-                            console.log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
+                            log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
                         }
                     }
                 }
                 else {
-                    console.log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                    log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
                 }
             }
             else {
-                console.log(chalk.gray(`Run 'agents cli install' to install them.`));
+                log(chalk.gray(`Run 'agents cli install' to install them.`));
             }
         }
     }
     catch (err) {
         if (!isPromptCancelled(err)) {
-            console.log(chalk.yellow(`CLI install skipped: ${err.message}`));
+            log(chalk.yellow(`CLI install skipped: ${err.message}`));
         }
     }
 }