loadout-ai 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.1 - 2026-07-20
+
+### Added
+
+- Detect local Node CLI, npm package, release, Vitest, Commander, Zod, MCP,
+  and security signals when recommending project tooling.
+- Label recommendations as skill libraries, explicit MCP/runtime setup, or
+  unavailable instead of presenting every catalog record as automatically
+  activatable.
+
+### Changed
+
+- Calculate project activation capacity separately for each agent and count
+  both Loadout-managed and pre-existing unmanaged skills toward `--limit`.
+- Prefer compact, diverse project skill sets and reject mismatched Jest-only
+  guidance for Vitest-only repositories.
+
+### Fixed
+
+- Allow project activation through recursively empty directories restored by
+  rollback while continuing to block files, symlinks, unreadable paths, and
+  unsupported entries.
+- Re-check per-agent capacity and target occupancy inside the activation
+  transaction so filesystem changes after preview abort without partial edits.
+
 ## 0.4.0 - 2026-07-20
 
 ### Added

package/MASTER_PLAN.md

@@ -92,9 +92,12 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       observed failure and turn reproducible ones into regression tests.
 - [ ] `P18-13 [HUMAN+TERRA]` Publish `loadout-ai@0.4.0` to npm, then test that exact
       registry tarball in a fresh terminal through Stable -> rollback -> Power ->
-      rollback -> Maximum -> project optimization -> dashboard -> complete uninstall.
-      The registry exposed versions only through `0.3.1` before this release attempt;
-      local package metadata and a Git tag do not prove publication.
+      rollback -> Maximum -> project optimization -> complete uninstall.
+      Publication completed on July 20. A clean temporary install resolved the exact
+      registry tarball, reported version `0.4.0`, and completed `loadout demo` with
+      rollback verification. The founder's real Codex/Claude CLI lifecycle test
+      remains required before this item can be checked; dashboard testing was removed
+      after founder review rejected it as a conflicting product surface.
 - [ ] `P18-17 [HUMAN]` Resolve the GitHub account billing or spending-limit condition
       that prevents Actions jobs from starting, rerun CI and daily discovery on the
       integrated commit, and record the result. CI runs
@@ -107,6 +110,94 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       GitHub currently returns 404 for the protection endpoint, so protection is
       absent or not observable; do not describe it as enabled.
 
+### Founder acceptance findings and 0.4.1 corrections
+
+- [x] `P18-21A [HUMAN+TERRA]` Verify the published 0.4.0 Stable lifecycle on the
+      founder's real Claude Code and Codex paths. Stable installed four pinned sources
+      as 60 managed activations, preserved all 12 unmanaged Claude skills, reported no
+      managed drift, and restored the explicit pre-install snapshot successfully.
+- [ ] `P18-21B [TERRA]` Make rollback history understandable before 0.4.1. The first
+      founder test exposed that bare `loadout rollback` selected a newer no-op
+      dashboard/sync snapshot whose pre-state already contained Stable. No data was
+      lost, but `rollback --list` showed opaque IDs only and `Restored snapshot` did
+      not disclose that zero effective files changed. Add timestamp, mutation kind,
+      affected scope, and no-op/current-state guidance; add a regression journey with
+      two adjacent snapshots and explicit older-snapshot rollback.
+- [ ] `P18-22 [TERRA]` Remove the dashboard before the public release. Founder review
+      confirmed that it presents recommendation presets (`stable`, `web`,
+      `collaboration`, `maximum`) as policy profiles while the real CLI contract is
+      `stable`, `power`, `maximum`, and `custom`; its manifest-sync mutation model is
+      not the CLI setup workflow. Remove the command, loopback server, browser assets,
+      dashboard-only dependencies/tests/docs/evidence, and npm package contents.
+      Preserve any unique useful inspection capability through existing CLI commands.
+- [ ] `P18-23 [HUMAN+TERRA]` Complete the remaining CLI-only founder path on the exact
+      npm package. Power and its explicit rollback are complete: snapshot
+      `1784546929191-9cfb0705dbed` restored zero Loadout-managed activations, retained
+      all 12 unmanaged Claude skills, returned Codex to zero skills, and left no
+      duplicate groups. Maximum setup is also complete: snapshot
+      `1784547473319-7581eb19ee9c` stored 2,316 screened skill copies from 29 packages
+      in the disabled library, activated none of them, and again preserved the 12
+      unmanaged Claude skills. Remaining path: project activation -> recommendation/
+      optimization -> Graphify install/remove -> credential-free MCP inventory ->
+      read-only update/discovery -> complete uninstall -> reinstall. Record every
+      mutation snapshot ID and use explicit rollback IDs during acceptance.
+- [ ] `P18-24 [SOL+TERRA]` Redesign Power before 0.4.1 based on the real founder run.
+      The published transaction itself passed: eight immutable sources installed for
+      Claude Code and Codex, 100 managed activations were created, 12 unmanaged Claude
+      skills were preserved, duplicate targets were resolved, six rejected skill
+      units were excluded, and 1,170 managed files reported zero drift. The profile
+      policy failed acceptance: it activates 50 skills per agent despite Loadout's
+      recommended limit of 30; every selected package retained blocking static-risk
+      findings (79 total); only five of eight sources have an asserted SPDX license;
+      and one coarse prompt approves all package findings. Make Power a broad managed
+      library with no more than 30 project-relevant skills active per agent, preserve
+      per-package approval and rejection choices, persist and display excluded-unit
+      quarantine evidence, and make the health headline reflect blocking risk and
+      capacity failures instead of reporting the overall installation as healthy.
+      Add a release test proving Power preserves unmanaged skills, never exceeds its
+      active cap, reports every excluded unit and retained finding, and restores its
+      explicit setup snapshot without residue. The founder's published-package run
+      has now demonstrated that final rollback property successfully.
+- [ ] `P18-25 [LUNA+TERRA]` Make health output honest and focused for empty or unmanaged
+      profiles. After the successful Power rollback, `loadout health --explain` led
+      with `Loadout health: healthy` and then reported 28/100 critical evidence for
+      Claude Code, 0/100 unknown for Codex, and similarly verbose sections for every
+      detected agent. Use an explicit `not configured`/`no managed packages` overall
+      state instead of healthy, keep the default summary concise, and let users scope
+      detailed evidence to selected agents while preserving the full explanation on
+      request. Add empty-state and mixed detected-agent CLI regression tests.
+- [ ] `P18-26 [LUNA+TERRA]` Make Maximum's preview understandable without weakening
+      its safe defaults. The founder run proved the disabled-library contract, but
+      printed 50 unit-level quarantine blocks, 19 expected MCP/runtime deferrals, two
+      `No SKILL.md` preparation failures, and one coarse 28-package risk approval in
+      the default path. The subsequent scan reported 11 repository failures without
+      naming them. Default to a concise grouped summary with exact counts, severity,
+      source, and next commands; retain complete findings behind an explicit details
+      or JSON view. Classify no-skill MCP/runtime records as explicit setup rather
+      than failed skill preparation, distinguish high-confidence findings from likely
+      documentation/binary/metadata false positives, persist every excluded unit, and
+      name every failed repository with a short reason. Add snapshot tests for both
+      concise and detailed Maximum output.
+- [x] `P18-27 [SOL+TERRA, LUNA copy review]` Correct project-aware activation safety
+      and relevance using
+      `docs/superpowers/specs/2026-07-20-project-activation-safety-design.md`.
+      Founder preview proved that activation currently ignores 12 unmanaged Claude
+      skills when calculating `--limit 30`, treats rollback-restored empty directories
+      as occupied for both agents, and proposes a generic, redundant 30-skill set from
+      only JavaScript/TypeScript and Playwright signals. Implement the approved shared
+      empty-target predicate, per-agent total active capacity, bounded Node CLI/npm/
+      Vitest/MCP project signals, diverse evidence-threshold selection, integration-
+      type labels, atomic apply revalidation, and the specified regression suite.
+      Implementation is complete on `codex/project-activation-safety`: the full local
+      release gate passes, including 114 unit-test files with 605 passing tests and
+      one intentional skip; the disposable two-agent CLI journey proves 12 unmanaged
+      Claude skills, distinct Claude/Codex budgets, empty rollback residue, one atomic
+      apply, and explicit rollback; the packed artifact is 468.0 kB with 145 files;
+      and the fresh scan benchmark passed at 1,583.5 ms p95 across seven real CLI
+      runs. Do
+      not resume real-profile activation until this branch is reviewed, integrated,
+      versioned, and published as the corrected release.
+
 ### Release 0.3 lifecycle hardening
 
 - [x] `P18-09 [SOL+TERRA]` Add preview-first complete uninstall with modified-file

package/README.md

@@ -26,7 +26,7 @@
 </p>
 
 > [!IMPORTANT]
-> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.4.0`; review the preview before every apply.
+> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.4.1`; review the preview before every apply.
 
 ## How it works
 
@@ -76,7 +76,7 @@ Skills, plugins, MCP servers, and agent settings tend to accumulate one experime
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.4.0
+npm install --global loadout-ai@0.4.1
 loadout --version
 loadout guide
 ```

package/dist/src/cli.js

@@ -265,7 +265,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.4.0";
+const LOADOUT_VERSION = "0.4.1";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),

package/dist/src/core/active-policy.js

@@ -1,5 +1,7 @@
 import { applyActivationChange, formatActivationPlan, planActivationChange, } from "./active-set.js";
-import { scanProject } from "./recommend.js";
+import { detectAgents } from "./paths.js";
+import { formatDetectedSignals, scanProject } from "./recommend.js";
+import { scanInstalledSkills } from "./skill-inventory.js";
 import { readInstallState } from "./state.js";
 import { outcomeAdjustment, projectTaskFamilies, readLocalOutcomes, } from "./outcomes.js";
 const FOUNDATION = new Set([
@@ -85,7 +87,77 @@ const SIGNAL_RULES = [
         pattern: /playwright|e2e|webapp-testing/,
         label: "Playwright project",
     },
+    {
+        signal: (project) => project.roles.includes("node-cli"),
+        pattern: /(?:^|-)cli(?:-|$)|command-line/,
+        label: "Node CLI",
+    },
+    {
+        signal: (project) => project.roles.includes("npm-package"),
+        pattern: /npm|package|publish/,
+        label: "npm package",
+    },
+    {
+        signal: (project) => project.roles.includes("release"),
+        pattern: /release|publish|package/,
+        label: "release automation",
+    },
+    {
+        signal: (project) => project.roles.includes("mcp"),
+        pattern: /mcp|model-context-protocol/,
+        label: "MCP tooling",
+    },
+    {
+        signal: (project) => project.roles.includes("security"),
+        pattern: /security|threat|secrets|owasp/,
+        label: "security policy",
+    },
+    {
+        signal: (project) => project.tools.includes("vitest"),
+        pattern: /vitest/,
+        label: "Vitest",
+    },
+    {
+        signal: (project) => project.tools.includes("commander"),
+        pattern: /(?:^|-)cli(?:-|$)|commander|command-line/,
+        label: "Commander CLI",
+    },
+    {
+        signal: (project) => project.tools.includes("zod"),
+        pattern: /zod|schema|validation/,
+        label: "Zod schemas",
+    },
 ];
+const FAMILY_CAPS = {
+    "browser-testing": 3,
+    documentation: 2,
+    "code-review": 2,
+    architecture: 2,
+    planning: 3,
+    security: 3,
+    "language-tooling": 5,
+    testing: 3,
+    uncategorized: 3,
+};
+function candidateFamily(unitId) {
+    if (/playwright|e2e|webapp-testing|browser-testing/.test(unitId))
+        return "browser-testing";
+    if (/docs|documentation|readme/.test(unitId))
+        return "documentation";
+    if (/review|refactor/.test(unitId))
+        return "code-review";
+    if (/architect|api-design|openapi/.test(unitId))
+        return "architecture";
+    if (/brainstorm|planning|writing-plans/.test(unitId))
+        return "planning";
+    if (/security|threat|secrets|owasp/.test(unitId))
+        return "security";
+    if (/test|coverage|vitest|jest/.test(unitId))
+        return "testing";
+    if (/javascript|typescript|nodejs|npm|package|cli|zod|schema/.test(unitId))
+        return "language-tooling";
+    return "uncategorized";
+}
 function selector(record) {
     if (!record.unitId)
         return undefined;
@@ -96,6 +168,10 @@ function scoreCandidate(record, project, pinned, outcomes, taskFamilies) {
     if (!id || !record.unitId)
         return undefined;
     const name = record.unitId.toLowerCase();
+    if (/(?:^|-)jest(?:-|$)/.test(name) &&
+        project.tools.includes("vitest") &&
+        !project.tools.includes("jest"))
+        return undefined;
     let score = 0;
     const reasons = [];
     if (pinned.has(id) || pinned.has(record.unitId)) {
@@ -136,25 +212,8 @@ function scoreCandidate(record, project, pinned, outcomes, taskFamilies) {
         reasons: [...new Set(reasons)],
     };
 }
-/** Deterministic, local-only active-set selection over the reviewed library. */
-export async function planProjectActivation(projectPath, options = {}) {
-    const limit = options.limit ?? 40;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
-        throw new Error("--limit must be an integer from 1 to 200");
-    const project = await scanProject(projectPath);
-    const state = await readInstallState();
-    const outcomes = await readLocalOutcomes();
-    const taskFamilies = projectTaskFamilies(project);
-    const relevant = (state.activations ?? []).filter((record) => record.installationState === "installed" &&
-        (!options.agents || options.agents.includes(record.agent)));
-    const byAgent = new Map();
-    for (const record of relevant)
-        if (record.activationState === "active")
-            byAgent.set(record.agent, (byAgent.get(record.agent) ?? 0) + 1);
-    const activeBefore = Math.max(0, ...byAgent.values());
-    const capacity = Math.max(0, limit - activeBefore);
-    const pins = new Set(options.pins ?? []);
-    const scored = relevant
+function rankedCandidates(records, project, pins, outcomes, taskFamilies) {
+    const scored = records
         .filter((record) => record.activationState === "disabled" &&
         record.cacheState === "downloaded" &&
         record.reviewState === "reviewed")
@@ -165,19 +224,24 @@ export async function planProjectActivation(projectPath, options = {}) {
             (SOURCE_PRIORITY[left.packageId] ?? 0) ||
         left.unitId.localeCompare(right.unitId) ||
         left.packageId.localeCompare(right.packageId));
-    // One capability name wins by evidence order; overlapping collections remain
-    // in the library and can still be explicitly pinned by full selector.
     const unique = [];
     const claimedUnits = new Set();
+    const familyCounts = new Map();
     for (const item of scored) {
         const fullPin = pins.has(item.selector);
         if (!fullPin && claimedUnits.has(item.unitId))
             continue;
+        const family = candidateFamily(item.unitId);
+        if (!fullPin && (familyCounts.get(family) ?? 0) >= FAMILY_CAPS[family])
+            continue;
         claimedUnits.add(item.unitId);
+        familyCounts.set(family, (familyCounts.get(family) ?? 0) + 1);
         unique.push(item);
     }
-    const selected = unique.slice(0, capacity);
-    const alternatives = selected.flatMap((chosen) => {
+    return unique;
+}
+function alternativesFor(selected, scored) {
+    return selected.flatMap((chosen) => {
         const deferred = scored
             .filter((candidate) => candidate.unitId === chosen.unitId &&
             candidate.selector !== chosen.selector)
@@ -186,7 +250,67 @@ export async function planProjectActivation(projectPath, options = {}) {
             ? [{ unitId: chosen.unitId, selected: chosen.selector, deferred }]
             : [];
     });
+}
+/** Deterministic, local-only active-set selection over the reviewed library. */
+export async function planProjectActivation(projectPath, options = {}) {
+    const limit = options.limit ?? 40;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+        throw new Error("--limit must be an integer from 1 to 200");
+    const project = await scanProject(projectPath);
+    const state = await readInstallState();
+    const outcomes = await readLocalOutcomes();
+    const taskFamilies = projectTaskFamilies(project);
+    const relevant = (state.activations ?? []).filter((record) => record.installationState === "installed" &&
+        (!options.agents || options.agents.includes(record.agent)));
+    const requestedAgents = options.agents ?? [
+        ...new Set(relevant.map((record) => record.agent)),
+    ];
+    const detected = (await detectAgents()).filter((agent) => requestedAgents.includes(agent.id));
+    const inventory = await scanInstalledSkills(detected);
+    const pins = new Set(options.pins ?? []);
     const warnings = [];
+    const agentPlans = requestedAgents.map((agent) => {
+        const summary = inventory.agents.find((item) => item.agent === agent);
+        if (!summary)
+            throw new Error(`Could not scan active skills for requested agent '${agent}'`);
+        const capacity = Math.max(0, limit - summary.total);
+        const ranked = rankedCandidates(relevant.filter((record) => record.agent === agent), project, pins, outcomes, taskFamilies);
+        const selected = ranked.slice(0, capacity);
+        if (!capacity)
+            warnings.push(`${summary.displayName} has reached the active-set limit ${limit}; disable skills or raise --limit.`);
+        return {
+            agent,
+            displayName: summary.displayName,
+            activeBefore: summary.total,
+            managedBefore: summary.managed,
+            unmanagedBefore: summary.unmanaged,
+            capacity,
+            selected,
+            alternatives: alternativesFor(selected, ranked),
+        };
+    });
+    const activationPlans = await Promise.all(agentPlans
+        .filter((agentPlan) => agentPlan.selected.length)
+        .map((agentPlan) => planActivationChange("enable", agentPlan.selected.map((item) => item.selector), { agents: [agentPlan.agent] })));
+    const activation = activationPlans.length
+        ? {
+            action: "enable",
+            packages: [
+                ...new Set(activationPlans.flatMap((plan) => plan.packages)),
+            ],
+            requestedAgents,
+            changes: activationPlans.flatMap((plan) => plan.changes),
+            skipped: activationPlans.flatMap((plan) => plan.skipped),
+            blocked: activationPlans.some((plan) => plan.blocked),
+            warnings: activationPlans.flatMap((plan) => plan.warnings),
+        }
+        : undefined;
+    const selected = [
+        ...new Map(agentPlans
+            .flatMap((agentPlan) => agentPlan.selected)
+            .map((item) => [item.selector, item])).values(),
+    ];
+    const alternatives = agentPlans.flatMap((item) => item.alternatives);
     const known = new Set(relevant.flatMap((record) => {
         const id = selector(record);
         return id ? [id, record.unitId] : [];
@@ -194,17 +318,13 @@ export async function planProjectActivation(projectPath, options = {}) {
     const unknownPins = [...pins].filter((pin) => !known.has(pin));
     if (unknownPins.length)
         warnings.push(`Pinned skill(s) are not in the managed library: ${unknownPins.join(", ")}`);
-    if (!capacity)
-        warnings.push(`Active-set limit ${limit} is already reached; disable skills or raise --limit.`);
-    const activation = selected.length
-        ? await planActivationChange("enable", selected.map((item) => item.selector), { ...(options.agents ? { agents: options.agents } : {}) })
-        : undefined;
     return {
         project,
         limit,
         ...(options.agents ? { agents: options.agents } : {}),
-        activeBefore,
-        capacity,
+        agentPlans,
+        activeBefore: Math.max(0, ...agentPlans.map((item) => item.activeBefore)),
+        capacity: Math.min(limit, ...agentPlans.map((item) => item.capacity)),
         selected,
         alternatives,
         ...(activation ? { activation } : {}),
@@ -214,17 +334,31 @@ export async function planProjectActivation(projectPath, options = {}) {
 export async function applyProjectActivation(plan) {
     if (!plan.activation || !plan.selected.length)
         throw new Error("No reviewed library skills were selected for activation");
-    return applyActivationChange(plan.activation);
+    return applyActivationChange(plan.activation, {
+        preflight: async () => {
+            const requested = plan.agentPlans.map((item) => item.agent);
+            const detected = (await detectAgents()).filter((agent) => requested.includes(agent.id));
+            const inventory = await scanInstalledSkills(detected);
+            for (const agentPlan of plan.agentPlans) {
+                const current = inventory.agents.find((item) => item.agent === agentPlan.agent);
+                if (!current)
+                    throw new Error(`Could not re-scan active skills for requested agent '${agentPlan.agent}'`);
+                if (current.total + agentPlan.selected.length > plan.limit)
+                    throw new Error(`${agentPlan.displayName} active skill capacity changed after preview: ${current.total} active plus ${agentPlan.selected.length} proposed exceeds limit ${plan.limit}`);
+            }
+        },
+    });
 }
 export function formatProjectActivation(plan) {
-    const detected = [...plan.project.languages, ...plan.project.frameworks];
     return [
         `Project: ${plan.project.root}`,
-        `Detected: ${detected.join(", ") || "no known project signals"}`,
-        `Active-set budget: ${plan.activeBefore}/${plan.limit} active; ${plan.capacity} slot(s) available`,
-        `Proposed additions: ${plan.selected.length}`,
-        ...plan.selected.map((item) => `  + ${item.selector} [${item.score}] — ${item.reasons.join(", ")}`),
-        ...plan.alternatives.map((item) => `  = ${item.unitId}: selected ${item.selected}; deferred equivalent source(s): ${item.deferred.join(", ")}`),
+        `Detected: ${formatDetectedSignals(plan.project) || "no known project signals"}`,
+        ...plan.agentPlans.flatMap((agentPlan) => [
+            `${agentPlan.displayName}: ${agentPlan.activeBefore} active (${agentPlan.managedBefore} managed, ${agentPlan.unmanagedBefore} unmanaged); ${agentPlan.capacity}/${plan.limit} slots available`,
+            `Proposed additions for ${agentPlan.displayName}: ${agentPlan.selected.length}`,
+            ...agentPlan.selected.map((item) => `  + ${item.selector} [${item.score}] — ${item.reasons.join(", ")}`),
+            ...agentPlan.alternatives.map((item) => `  = ${item.unitId}: selected ${item.selected}; deferred equivalent source(s): ${item.deferred.join(", ")}`),
+        ]),
         ...(plan.activation
             ? ["", "Exact activation delta:", formatActivationPlan(plan.activation)]
             : []),

package/dist/src/core/active-set.js

@@ -3,6 +3,7 @@ import { cp, lstat, mkdir, readFile, readdir, rm } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { agentSkillsDirectory, ensureDirectory } from "./paths.js";
 import { activationLibraryPath, installStatePath, readInstallState, writeInstallState, } from "./state.js";
+import { inspectTargetOccupancy } from "./target-occupancy.js";
 import { runMutationTransaction } from "./transaction.js";
 /** Resolve a managed file to its active location or disabled library copy. */
 export function managedFileReadPath(packageId, filePath, activations) {
@@ -262,9 +263,12 @@ export async function planActivationChange(action, packageIds, options = {}) {
                     const libraryActual = await hashTree(record.libraryPath);
                     change.blockers.push(...exactTreeDifferences(record.libraryFiles, libraryActual).map((message) => `library copy: ${message}`));
                 }
-                const occupied = (await Promise.all(change.targets.map((target) => pathExists(target.activePath)))).filter(Boolean).length;
-                if (occupied)
-                    change.blockers.push(`${occupied} active target(s) already exist and would be overwritten`);
+                const occupied = (await Promise.all(change.targets.map(async (target) => ({
+                    target,
+                    result: await inspectTargetOccupancy(target.activePath),
+                })))).filter((item) => item.result.occupied);
+                if (occupied.length)
+                    change.blockers.push(`${occupied.length} active target(s) already contain protected content and would be overwritten; first target: ${occupied[0].target.activePath} (${occupied[0].result.reason})`);
             }
             changes.push(change);
         }
@@ -283,8 +287,9 @@ export async function planActivationChange(action, packageIds, options = {}) {
 function activationKey(record) {
     return `${record.packageId}\0${record.agent}\0${record.unitId ?? ""}`;
 }
-export async function applyActivationChange(plan) {
+export async function applyActivationChange(plan, options = {}) {
     const applied = await runMutationTransaction(async () => {
+        await options.preflight?.();
         const fresh = await planActivationChange(plan.action, plan.packages, {
             ...(plan.requestedAgents ? { agents: plan.requestedAgents } : {}),
         });
@@ -337,6 +342,10 @@ export async function applyActivationChange(plan) {
             else {
                 for (const target of change.targets) {
                     const source = join(change.libraryPath, target.libraryRelativePath);
+                    const occupancy = await inspectTargetOccupancy(target.activePath);
+                    if (occupancy.occupied)
+                        throw new Error(`${change.packageId}/${change.agent}: activation target became occupied: ${target.activePath} (${occupancy.reason})`);
+                    await rm(target.activePath, { recursive: true, force: true });
                     await mkdir(dirname(target.activePath), { recursive: true });
                     await cp(source, target.activePath, {
                         recursive: true,

package/dist/src/core/install.js

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
-import { cp, lstat, readdir, rm } from "node:fs/promises";
+import { cp, lstat, rm } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, posix, relative, win32, } from "node:path";
 import { ensureDirectory, loadoutHome } from "./paths.js";
 import { planAdapterSkillInstall } from "./adapters.js";
 import { applySkillPlan, detectInstallConflicts } from "./skills.js";
 import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, writeInstallState, } from "./state.js";
 import { runMutationTransaction } from "./transaction.js";
+import { inspectTargetOccupancy } from "./target-occupancy.js";
 export function installedAgents(agents, requested) {
     const available = agents.filter((agent) => agent.installed);
     if (!requested || requested.length === 0)
@@ -116,42 +117,8 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
     for (const target of [
         ...new Set(plans.flatMap((plan) => plan.files.map((file) => file.target))),
     ])
-        try {
-            const info = await lstat(target);
-            if (info.isDirectory() && !info.isSymbolicLink()) {
-                const queue = [target];
-                let entriesChecked = 0;
-                let empty = true;
-                while (queue.length && empty) {
-                    const directory = queue.pop();
-                    for (const entry of await readdir(directory, {
-                        withFileTypes: true,
-                    })) {
-                        entriesChecked += 1;
-                        if (entriesChecked > 10_000) {
-                            empty = false;
-                            break;
-                        }
-                        if (entry.isDirectory() && !entry.isSymbolicLink())
-                            queue.push(join(directory, entry.name));
-                        else {
-                            empty = false;
-                            break;
-                        }
-                    }
-                }
-                if (empty)
-                    continue;
-            }
+        if ((await inspectTargetOccupancy(target)).occupied)
             occupied.push(target);
-        }
-        catch (error) {
-            if (!error ||
-                typeof error !== "object" ||
-                !("code" in error) ||
-                error.code !== "ENOENT")
-                throw error;
-        }
     if (occupied.length && options.allowManagedReplacement) {
         const state = await readInstallState();
         const allowed = new Map();