@phnx-labs/agents-cli 1.22.76 → 1.22.77

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.22.77
+
+- **`agents repo pull` / `agents sync` no longer wedge on a CLI-regenerated `~/.agents/agents.yaml` (PHNX-3968).** The shared central config was rewritten by config commands without being committed, so between the daemon's publish ticks the tree sat dirty on `agents.yaml`; an incoming peer commit that also touched it made the pull refuse with *"incoming changes touch uncommitted paths: agents.yaml"*, forcing manual autostash gymnastics on the fleet. Central config edits are now committed synchronously by the command that makes them (after the meta lock releases, skipped for the daemon whose own publish tick owns its commits), so the tree is clean at rest and the trip cannot occur. A genuinely dirty-and-differing central file now *refuses* the pull (data-safe, self-heals on the next commit) rather than silently taking the remote copy. The user-repo `CHANGELOG.md` (a duplicate of the shipped one) is de-tracked via `.git/info/exclude` so it stops churning the tree. Source: `cli/src/lib/state.ts`, `cli/src/lib/git.ts`, `cli/src/lib/browser/registry.ts`, `cli/src/lib/project-resources.ts`.
+
 ## 1.22.76
 
 - **Per-session summarizer: bound the mirror publish (PHNX-3939 follow-up).** The fleet session mirror now caps `checkpoints`/`summaryChecklist` on the **publish** side (50/100 items, 400-char text) exactly as it already did on consume, so a box's own summarizer output can never ride unbounded into the git-synced `daemon-state.json` every peer fetches — matching the `snippet()` cap already applied to `goal`. Source: `cli/src/lib/session/mirror.ts`.

package/dist/lib/browser/registry.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import * as yaml from 'yaml';
-import { getUserAgentsDir, readMeta, updateMeta, withMetaLock, writeMetaUnlocked } from '../state.js';
+import { commitCentralConfigAfterWrite, getUserAgentsDir, readMeta, updateMeta, withMetaLock, writeMetaUnlocked } from '../state.js';
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -168,7 +168,8 @@ export function autoEvictCentralBrowserProfiles(canHostHere) {
     // window. We write ONLY when something is claimed, so a no-op sync never touches
     // any doc (writeMetaUnlocked would otherwise re-serialize the device doc every
     // run). This mirrors updateMeta's own body, minus the unconditional write.
-    return withMetaLock(() => {
+    let centralChanged = false;
+    const result = withMetaLock(() => {
         const meta = readMeta();
         const central = meta.browser;
         if (!central || Object.keys(central).length === 0)
@@ -181,9 +182,15 @@ export function autoEvictCentralBrowserProfiles(canHostHere) {
         skipped.sort();
         if (claimed.length === 0)
             return { claimed, skipped };
-        writeMetaUnlocked(buildEvictedMeta(meta, toClaim));
+        centralChanged = writeMetaUnlocked(buildEvictedMeta(meta, toClaim));
         return { claimed, skipped };
     });
+    // Commit the central eviction AFTER the meta lock releases (the invariant:
+    // every non-daemon central write commits after the lock, so agents.yaml is
+    // never left dirty at rest to re-open the pull-trip window). Gated inside the
+    // helper on centralChanged && !isDaemonProcess().
+    commitCentralConfigAfterWrite(centralChanged);
+    return result;
 }
 /**
  * Every profile any device declares, keyed by name to all declaring devices.

package/dist/lib/git.js

@@ -1427,6 +1427,12 @@ async function dirtyTreeRefusal(git, status, upstreamRef) {
         .filter(Boolean);
     const collisions = incoming.filter((p) => dirty.has(p));
     if (collisions.length > 0) {
+        // Central agents.yaml is AUTHORITATIVE (account labels/rows), not regenerable,
+        // and a dirty copy always equals serializeCentral(current meta) — so no
+        // byte check can tell a stranded real edit from a stale one. Refuse rather
+        // than discard: it is data-safe and self-heals, because commit-on-write
+        // (lib/state.ts) and the daemon's publish tick both commit agents.yaml,
+        // after which the very next pull succeeds normally. See PHNX-3968.
         const shown = collisions.slice(0, 5).join(', ');
         const more = collisions.length > 5 ? ` (+${collisions.length - 5} more)` : '';
         return `incoming changes touch uncommitted paths: ${shown}${more}`;

package/dist/lib/installations/migrate.d.ts

@@ -2,6 +2,16 @@
 export { foldLegacySystemRepo } from '../migrate-fold.js';
 /** Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml. Leaves the tracked system-mirror copy alone to avoid dirtying the npm-shipped defaults. */
 export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
+/**
+ * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
+ * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
+ * file that upstream never carries it can only ever show as `M`/`??`
+ * — dirtying the tree and, when a peer's publish commit arrives, tripping the
+ * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
+ * uncommitted; never `.gitignore`, which would re-introduce the same failure).
+ * Idempotent: a no-op once the path is untracked and excluded.
+ */
+export declare function detrackUserChangelog(userDir?: string): void;
 /** Fold the legacy global browser/sessions/<task>/ tree into the per-profile browser/<profile>/sessions/<task>/ layout. Unclaimed tasks move under `_legacy`. */
 export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): void;
 /** Repair node_modules/.bin/<cli> symlinks that resolve back into our own shims dir (infinite exec-loop fix). */

package/dist/lib/installations/migrate.js

@@ -16,6 +16,7 @@ import { setConfigValue } from '../device-config.js';
 import { enabledRoutineNames, replaceEnabledRoutines } from '../routine-activation.js';
 import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
+import { detrackViaGitExclude } from '../project-resources.js';
 // Two constants only, never the read/write API — migrations still operate on raw
 // YAML so they never take the meta lock or prime the meta cache mid-migration.
 import { LEGACY_DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
@@ -70,6 +71,22 @@ function deleteSystemPromptsJson() {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
+ * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
+ * file that upstream never carries it can only ever show as `M`/`??`
+ * — dirtying the tree and, when a peer's publish commit arrives, tripping the
+ * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
+ * uncommitted; never `.gitignore`, which would re-introduce the same failure).
+ * Idempotent: a no-op once the path is untracked and excluded.
+ */
+export function detrackUserChangelog(userDir = USER_DIR) {
+    if (!fs.existsSync(path.join(userDir, '.git')))
+        return; // plain dir, not a clone
+    const untracked = detrackViaGitExclude(userDir, 'CHANGELOG.md');
+    if (untracked)
+        console.error('Stopped tracking ~/.agents/CHANGELOG.md (duplicates .system/CHANGELOG.md)');
+}
 /** Delete the legacy ~/.agents-system/config.json (dead teams agent registry). */
 function migrateSystemConfigJson() {
     const src = path.join(SYSTEM_DIR, 'config.json');
@@ -2242,6 +2259,7 @@ export async function runMigration() {
     migrateHumans();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
+    detrackUserChangelog();
     migratePromptcutsIntoHooks();
     migrateSystemVersionsToUser();
     mergeOverlappingVersionHomes();

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

@@ -21,6 +21,29 @@ export declare function syncProjectResourcesToAgent(agent: AgentId, version: str
  *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
  */
 export declare function managedGitignoreEntries(agentRoot: string, referenceRoot: string, managed: string[]): string[];
+/**
+ * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
+ * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
+ * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
+ * canonical copy ships in `.system/`).
+ *
+ * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
+ * `.gitignore` block would itself show as `M .gitignore` on every clone and
+ * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
+ * to kill. info/exclude is per-clone and never committed, so the working tree
+ * stays clean at rest.
+ *
+ * Idempotent and convergent: when the path is still tracked it is removed from
+ * the index (the working file is kept) AND that removal is committed — a bare
+ * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
+ * that re-arms the very pull trip this exists to prevent. The single removal
+ * commit also propagates the de-track fleet-wide: peers pull it and converge,
+ * their next run finding nothing to untrack. The exclude block is rewritten in
+ * place, unioning `relPath` with any entries already there, so a second run is a
+ * no-op. Fails open outside a git repo. Returns whether the path was untracked
+ * by this call (a signal for the caller's one-time log).
+ */
+export declare function detrackViaGitExclude(repoDir: string, relPath: string): boolean;
 /**
  * One human line for the files a project sync left alone because you already
  * wrote them. This is the normal steady state — every sync of a project whose

package/dist/lib/project-resources.js

@@ -284,6 +284,100 @@ function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
     fs.writeFileSync(tmp, stripped);
     fs.renameSync(tmp, gitignorePath);
 }
+const DETRACK_BEGIN = '# BEGIN agents-cli detracked (managed)';
+const DETRACK_END = '# END agents-cli detracked (managed)';
+/**
+ * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
+ * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
+ * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
+ * canonical copy ships in `.system/`).
+ *
+ * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
+ * `.gitignore` block would itself show as `M .gitignore` on every clone and
+ * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
+ * to kill. info/exclude is per-clone and never committed, so the working tree
+ * stays clean at rest.
+ *
+ * Idempotent and convergent: when the path is still tracked it is removed from
+ * the index (the working file is kept) AND that removal is committed — a bare
+ * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
+ * that re-arms the very pull trip this exists to prevent. The single removal
+ * commit also propagates the de-track fleet-wide: peers pull it and converge,
+ * their next run finding nothing to untrack. The exclude block is rewritten in
+ * place, unioning `relPath` with any entries already there, so a second run is a
+ * no-op. Fails open outside a git repo. Returns whether the path was untracked
+ * by this call (a signal for the caller's one-time log).
+ */
+export function detrackViaGitExclude(repoDir, relPath) {
+    const target = resolveGitExcludeTarget(repoDir);
+    if (!target)
+        return false; // not a git repo — nothing to de-track or ignore.
+    let untrackedNow = false;
+    const abs = path.join(repoDir, relPath);
+    if (isTrackedByGit(repoDir, abs)) {
+        try {
+            // Unstage anything else first so the removal commit records ONLY this
+            // path's deletion — a mixed reset (index only, worktree untouched). At
+            // migration time the index is already clean; this just makes the scope
+            // guaranteed rather than assumed.
+            execFileSync('git', ['-C', repoDir, 'reset', '-q'], { stdio: ['ignore', 'ignore', 'ignore'] });
+            // --cached keeps the working file; the commit records the removal so the
+            // tree is clean at rest and the de-track converges across the fleet. A
+            // pathspec commit would re-read the still-present worktree file and undo
+            // the removal, so the commit takes the staged index (just this deletion).
+            execFileSync('git', ['-C', repoDir, 'rm', '--cached', '--quiet', '--', relPath], {
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            execFileSync('git', ['-C', repoDir, '-c', 'commit.gpgsign=false', 'commit', '--no-verify',
+                '-m', `chore(config): stop tracking ${relPath}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+            untrackedNow = true;
+        }
+        catch {
+            // rm/commit can fail (e.g. mid-rebase, index.lock); the ignore entry below
+            // still lands and the next migration run retries the untrack. Fail open —
+            // but roll back a staged-but-uncommitted removal so we never LEAVE a dirty
+            // staged deletion behind (which would re-arm the pull trip).
+            try {
+                execFileSync('git', ['-C', repoDir, 'reset', '-q', '--', relPath], {
+                    stdio: ['ignore', 'ignore', 'ignore'],
+                });
+            }
+            catch { /* nothing staged to reset */ }
+            untrackedNow = false;
+        }
+    }
+    // Anchor to the worktree root so the pattern matches only the top-level file,
+    // exactly like git anchors a leading-slash info/exclude entry.
+    const entry = '/' + relPath.split(path.sep).join('/');
+    let original = '';
+    try {
+        original = fs.readFileSync(target.excludePath, 'utf-8');
+    }
+    catch {
+        original = '';
+    }
+    const existing = extractManagedEntries(original, DETRACK_BEGIN, DETRACK_END);
+    const entries = existing.includes(entry) ? existing : [...existing, entry].sort();
+    const next = applyManagedBlock(original, DETRACK_BEGIN, DETRACK_END, entries);
+    if (next !== null && next !== original) {
+        fs.mkdirSync(path.dirname(target.excludePath), { recursive: true });
+        const tmp = target.excludePath + '.tmp';
+        fs.writeFileSync(tmp, next);
+        fs.renameSync(tmp, target.excludePath);
+    }
+    return untrackedNow;
+}
+/** The entries currently inside a `begin`/`end` managed block, or `[]`. */
+function extractManagedEntries(content, begin, end) {
+    const lines = content.split('\n');
+    const bi = lines.indexOf(begin);
+    if (bi === -1)
+        return [];
+    const ei = lines.indexOf(end, bi + 1);
+    if (ei === -1)
+        return [];
+    return lines.slice(bi + 1, ei).map((l) => l.trim()).filter(Boolean);
+}
 function removeManagedPath(agentRoot, rel) {
     if (path.isAbsolute(rel) || rel.includes('..'))
         return;

package/dist/lib/state.d.ts

@@ -409,6 +409,33 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * Commit the central `agents.yaml` in the user repo, synchronously, so a CLI
+ * config mutation never leaves the working tree dirty on that one shared-line
+ * file at rest.
+ *
+ * Why this exists: CLI config commands rewrite the fleet-shared central
+ * agents.yaml as a plain file write. Left uncommitted, the tree is dirty on
+ * agents.yaml between the write and the daemon's next 15-min publish tick — and
+ * a peer's incoming publish commit (which also touches agents.yaml) then trips
+ * `dirtyTreeRefusal` ("incoming changes touch uncommitted paths: agents.yaml"),
+ * wedging `agents repo pull` fleet-wide (PHNX-3968). Committing the central edit
+ * in the same command that made it closes that window: agents.yaml is clean at
+ * rest, so nothing incoming can collide with it. Called AFTER the meta lock
+ * releases (see {@link commitCentralConfigAfterWrite}) so the git subprocesses
+ * never run inside the short, non-heartbeated lockfile window; the user repo
+ * already pushes.
+ *
+ * Scoped tightly: only called when the central bytes actually changed, and never
+ * from the daemon (see {@link isDaemonProcess}). A commit failure fails open —
+ * a concurrent daemon holding `index.lock`, a mid-rebase repo — leaving
+ * agents.yaml dirty; the next successful central write commits it, and until
+ * then a pull that would collide refuses rather than losing data. A config
+ * command must never fail because git hiccuped.
+ *
+ * Returns whether a commit was created. Exported for the real-repo tests.
+ */
+export declare function commitCentralConfig(userDir: string): boolean;
 /**
  * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
  * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
@@ -431,8 +458,13 @@ export declare function readTopLevelUserMeta(): Record<string, unknown> | null;
  * writer that needs to read fresh state, decide, and commit within a SINGLE lock
  * acquisition (e.g. browser tombstone eviction) can do so without the
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ *
+ * Returns whether the central `agents.yaml` bytes actually changed, so the
+ * caller can commit it once — {@link commitCentralConfig} — AFTER releasing the
+ * meta lock (the git subprocesses must not run inside the short, non-heartbeated
+ * lockfile window). This function never commits.
  */
-export declare function writeMetaUnlocked(meta: Meta): void;
+export declare function writeMetaUnlocked(meta: Meta): boolean;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *
@@ -448,6 +480,16 @@ export declare function readMeta(): Meta;
 export declare function writeMeta(meta: Meta): void;
 /** Update agents.yaml under lock and return the new state. */
 export declare function updateMeta(updates: Partial<Meta> | ((meta: Meta) => Meta)): Meta;
+/**
+ * Commit-on-write, invoked AFTER {@link withMetaLock} releases so the git
+ * subprocesses never run inside the short, non-heartbeated meta-lock window.
+ * A CLI command that actually moved the fleet-shared central agents.yaml commits
+ * it so the tree is never left dirty on that file at rest — the window that
+ * trips `dirtyTreeRefusal` and wedges pulls fleet-wide (PHNX-3968). Gated on a
+ * real byte change and never run in the daemon, whose publish tick owns central
+ * commits. See {@link commitCentralConfig}.
+ */
+export declare function commitCentralConfigAfterWrite(centralChanged: boolean): void;
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
 import type { AgentId, ResourceType, VersionResources, ResourcePattern } from './types.js';

package/dist/lib/state.js

@@ -850,7 +850,9 @@ export function withMetaLock(fn) {
     });
 }
 /** Atomic write only when the on-disk content differs — avoids needless mtime
- * bumps (which would thrash the meta cache) on no-op field routing. */
+ * bumps (which would thrash the meta cache) on no-op field routing. Returns
+ * whether it actually wrote, so a caller can react only to a real change (e.g.
+ * commit the central agents.yaml exactly when its bytes moved). */
 function writeIfChanged(filePath, content) {
     let current = null;
     try {
@@ -858,8 +860,74 @@ function writeIfChanged(filePath, content) {
     }
     catch { /* absent */ }
     if (current === content)
-        return;
+        return false;
     atomicWriteFileSync(filePath, content);
+    return true;
+}
+/**
+ * True in the always-on daemon process (launched as `agents __daemon-run`,
+ * see cli/src/index.ts). The daemon owns central git commits through
+ * fleet-shared-repo-sync's publish tick, so a central write from inside the
+ * daemon must NOT also commit here — that would race the publisher's own
+ * add/commit/rebase/push on the same index. Every ordinary CLI invocation
+ * returns false and commits its own central edit synchronously.
+ */
+function isDaemonProcess() {
+    return process.argv[2] === '__daemon-run';
+}
+/**
+ * Commit the central `agents.yaml` in the user repo, synchronously, so a CLI
+ * config mutation never leaves the working tree dirty on that one shared-line
+ * file at rest.
+ *
+ * Why this exists: CLI config commands rewrite the fleet-shared central
+ * agents.yaml as a plain file write. Left uncommitted, the tree is dirty on
+ * agents.yaml between the write and the daemon's next 15-min publish tick — and
+ * a peer's incoming publish commit (which also touches agents.yaml) then trips
+ * `dirtyTreeRefusal` ("incoming changes touch uncommitted paths: agents.yaml"),
+ * wedging `agents repo pull` fleet-wide (PHNX-3968). Committing the central edit
+ * in the same command that made it closes that window: agents.yaml is clean at
+ * rest, so nothing incoming can collide with it. Called AFTER the meta lock
+ * releases (see {@link commitCentralConfigAfterWrite}) so the git subprocesses
+ * never run inside the short, non-heartbeated lockfile window; the user repo
+ * already pushes.
+ *
+ * Scoped tightly: only called when the central bytes actually changed, and never
+ * from the daemon (see {@link isDaemonProcess}). A commit failure fails open —
+ * a concurrent daemon holding `index.lock`, a mid-rebase repo — leaving
+ * agents.yaml dirty; the next successful central write commits it, and until
+ * then a pull that would collide refuses rather than losing data. A config
+ * command must never fail because git hiccuped.
+ *
+ * Returns whether a commit was created. Exported for the real-repo tests.
+ */
+export function commitCentralConfig(userDir) {
+    const rel = 'agents.yaml';
+    try {
+        execFileSync('git', ['-C', userDir, 'rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+    }
+    catch {
+        return false; // plain ~/.agents with no git repo — leave it a loose write.
+    }
+    try {
+        execFileSync('git', ['-C', userDir, 'add', '--', rel], { stdio: 'ignore' });
+        // Nothing staged for agents.yaml (its bytes matched HEAD after all) → no
+        // empty commit. `diff --cached --quiet` exits 0 when the index equals HEAD
+        // for this path, 1 when it differs.
+        try {
+            execFileSync('git', ['-C', userDir, 'diff', '--cached', '--quiet', '--', rel], { stdio: 'ignore' });
+            return false;
+        }
+        catch { /* exit 1 → staged changes present, commit them */ }
+        // Pathspec-scoped commit: records ONLY agents.yaml even if other paths are
+        // staged, so a config write never sweeps unrelated staged work into its commit.
+        execFileSync('git', ['-C', userDir, '-c', 'commit.gpgsign=false', 'commit', '--no-verify',
+            '-m', 'chore(config): update agents.yaml', '--', rel], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false; // fail open — see the doc comment.
+    }
 }
 /**
  * Partition the in-memory Meta across four files by sync-domain:
@@ -1149,6 +1217,11 @@ function serializeCentral(central) {
  * writer that needs to read fresh state, decide, and commit within a SINGLE lock
  * acquisition (e.g. browser tombstone eviction) can do so without the
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ *
+ * Returns whether the central `agents.yaml` bytes actually changed, so the
+ * caller can commit it once — {@link commitCentralConfig} — AFTER releasing the
+ * meta lock (the git subprocesses must not run inside the short, non-heartbeated
+ * lockfile window). This function never commits.
  */
 export function writeMetaUnlocked(meta) {
     const writesDeviceRoutines = Object.prototype.hasOwnProperty.call(meta, 'deviceRoutines');
@@ -1306,8 +1379,9 @@ export function writeMetaUnlocked(meta) {
         fs.mkdirSync(path.dirname(vrPath), { recursive: true });
         writeIfChanged(vrPath, JSON.stringify(versions, null, 2) + '\n');
     }
-    writeIfChanged(META_FILE, serializeCentral(central));
+    const centralChanged = writeIfChanged(META_FILE, serializeCentral(central));
     metaCache = null;
+    return centralChanged;
 }
 /**
  * Overlay this machine's local state onto a central-portable Meta:
@@ -1493,7 +1567,15 @@ export function readMeta() {
             if (parsed.registries) {
                 meta.registries = parsed.registries;
             }
-            writeMeta(meta);
+            // Lock-safe, commit-free write: withMetaLock is reentrant (see
+            // metaLockDepth), so this writes under the lock when called standalone and
+            // is a no-op re-entry when readMeta runs inside updateMeta/writeMeta's held
+            // lock — and writeMetaUnlocked never spawns git. Calling the PUBLIC
+            // writeMeta here would run commit-on-write's git subprocess inside a held,
+            // non-heartbeated lock. This one-shot legacy migration needs no synchronous
+            // commit: it self-heals on the daemon's next publish tick or the next real
+            // CLI central write.
+            withMetaLock(() => writeMetaUnlocked(meta));
             try {
                 fs.unlinkSync(oldMetaFile);
             }
@@ -1547,18 +1629,36 @@ export function readMeta() {
 }
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {
-    withMetaLock(() => writeMetaUnlocked(meta));
+    const centralChanged = withMetaLock(() => writeMetaUnlocked(meta));
+    commitCentralConfigAfterWrite(centralChanged);
 }
 /** Update agents.yaml under lock and return the new state. */
 export function updateMeta(updates) {
-    return withMetaLock(() => {
+    let centralChanged = false;
+    const newMeta = withMetaLock(() => {
         const meta = readMeta();
-        const newMeta = typeof updates === 'function'
+        const nm = typeof updates === 'function'
             ? updates(meta)
             : { ...meta, ...updates };
-        writeMetaUnlocked(newMeta);
-        return newMeta;
+        centralChanged = writeMetaUnlocked(nm);
+        return nm;
     });
+    commitCentralConfigAfterWrite(centralChanged);
+    return newMeta;
+}
+/**
+ * Commit-on-write, invoked AFTER {@link withMetaLock} releases so the git
+ * subprocesses never run inside the short, non-heartbeated meta-lock window.
+ * A CLI command that actually moved the fleet-shared central agents.yaml commits
+ * it so the tree is never left dirty on that file at rest — the window that
+ * trips `dirtyTreeRefusal` and wedges pulls fleet-wide (PHNX-3968). Gated on a
+ * real byte change and never run in the daemon, whose publish tick owns central
+ * commits. See {@link commitCentralConfig}.
+ */
+export function commitCentralConfigAfterWrite(centralChanged) {
+    if (centralChanged && !isDaemonProcess()) {
+        commitCentralConfig(USER_AGENTS_DIR);
+    }
 }
 /** Derive a filesystem-safe local clone path for a package source URL. */
 export function getPackageLocalPath(source) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.76",
+  "version": "1.22.77",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",