packages/mosaic/src/commands/fleet-launch-command.spec.ts

@@ -242,6 +242,28 @@ describe('managed plugin and skill links', () => {
     );
   });
 
+  it('tolerates harness metadata files in the install root and still refuses real directories', () => {
+    const fx = fixture({ schema: 1, harness: 'claude', plugins: [] });
+    const pluginHome = join(fx.agentDir, '.claude', 'plugins');
+    mkdirSync(pluginHome, { recursive: true });
+    writeFileSync(join(pluginHome, 'installed_plugins.json'), '{}\n');
+
+    const plan = resolveFleetLaunchComposition('fred', {
+      systemHome: fx.systemHome,
+      userHome: fx.userHome,
+    });
+    expect(plan.prune).toEqual([]);
+    expect(readFileSync(join(pluginHome, 'installed_plugins.json'), 'utf8')).toBe('{}\n');
+
+    mkdirSync(join(pluginHome, 'stray-plugin'), { recursive: true });
+    expect(() =>
+      resolveFleetLaunchComposition('fred', {
+        systemHome: fx.systemHome,
+        userHome: fx.userHome,
+      }),
+    ).toThrowError(/real plugin directory occupies managed install root.*refusing to prune/i);
+  });
+
   it('surfaces a real directory at a managed link path without deleting it', () => {
     const fx = fixture({ schema: 1, harness: 'claude', plugins: ['keep'] });
     mkdirSync(join(fx.userHome, 'plugins', 'keep'), { recursive: true });

packages/mosaic/src/commands/fleet-launch-command.ts

@@ -498,10 +498,16 @@ function resolveManagedLinks(
       const path = join(installRoot, entry.name);
       if (desired.has(entry.name)) continue;
       if (!entry.isSymbolicLink()) {
-        throw new FleetLaunchError(
-          'COMPOSITION_FAILED',
-          `real ${kind} entry occupies managed install root ${path}; refusing to prune it.`,
-        );
+        // The harness writes its own metadata files (e.g. installed_plugins.json)
+        // beside the managed links; only a real directory is an unmanaged entry
+        // the pruner would orphan.
+        if (entry.isDirectory()) {
+          throw new FleetLaunchError(
+            'COMPOSITION_FAILED',
+            `real ${kind} directory occupies managed install root ${path}; refusing to prune it.`,
+          );
+        }
+        continue;
       }
       prune.push(path);
     }