loadout-ai 0.3.1 → 0.4.1

package/dist/src/cli.js

@@ -20,8 +20,8 @@ import { buildHealthReport, formatHealthReport } from "./core/health.js";
 import { readInstallState, recordInstallTransaction } from "./core/state.js";
 import { applyRemove, planRemove } from "./core/remove.js";
 import { applyUninstall, buildUninstallPlan, formatUninstallPlan, uninstallGlobalCli, } from "./core/uninstall.js";
-import { evaluateInstalledProfile, formatInstalledProfileStatus, recordInstalledProfile, } from "./core/profile-state.js";
-import { formatRecommendations, personalizeRecommendations, profileManifestPackages, recommendPackages, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
+import { evaluateInstalledProfile, formatInstalledProfileStatus, } from "./core/profile-state.js";
+import { formatRecommendations, personalizeRecommendations, profileManifestPackages, recommendPackages, RECOMMENDATION_BOUNDARY, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
 import { buildImprovementCycle, formatImprovementCycle, recordImprovementOutcome, writeImprovementCycle, } from "./core/improve.js";
 import { applySyncPlan, buildSyncPlan } from "./core/sync.js";
 import { createPackage, packPackage, publishLocalPackage, publishRemotePackage, searchLocalRegistry, } from "./core/registry.js";
@@ -33,7 +33,7 @@ import { generateSigningKeys, signJsonFile, verifyJsonFile, } from "./core/signi
 import { applyPortableImport, exportPortableLoadout, planPortableImport, } from "./core/portable.js";
 import { applyCodexMcpConfigPlan, defaultCodexMcpConfigPath, planCodexMcpConfig, } from "./core/codex-mcp.js";
 import { formatDemoResult, runIsolatedDemo } from "./core/demo.js";
-import { catalogTrustStage, resolveCatalogProfile } from "./core/profiles.js";
+import { catalogTrustStage, formatCatalogTrustStage, resolveCatalogProfile, } from "./core/profiles.js";
 import { discoverHackerNewsRepositories } from "./core/community.js";
 import { discoverPrivateRepositories } from "./core/private-discovery.js";
 import { defaultGitHubDiscoveryQueries, discoverGitHubRepositories, } from "./core/github-discovery.js";
@@ -45,7 +45,7 @@ import { compileConversion, } from "./core/conversion.js";
 import { writeFileAtomically } from "./core/atomic-file.js";
 import { formatCanaryResult, runCanary } from "./core/canary.js";
 import { startDashboardServer } from "./dashboard.js";
-import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./core/catalog-install.js";
+import { applyPreparedCatalogInstall, formatCatalogApplyGuidance, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./core/catalog-install.js";
 import { formatInstalledSkillInventory, scanInstalledSkills, } from "./core/skill-inventory.js";
 import { enrichInventoryWithProvenance, formatProvenanceSummary, resolveCatalogSkillIndex, } from "./core/provenance.js";
 import { compareSkill, formatSkillComparison } from "./core/skill-compare.js";
@@ -183,14 +183,14 @@ async function runSetup(options) {
     try {
         if (!mode) {
             if (!interactive) {
-                console.log("Loadout is CLI-first. Run `loadout setup --mode stable` for the recommended daily driver, `--mode power` for broader opt-in skills, or `--mode maximum` to download the screened library without activating it.");
+                console.log("Loadout is CLI-first. Run `loadout setup --mode stable` for Loadout's bounded policy selection, `--mode power` for broader opt-in skills, or `--mode maximum` to download the screened library without activating it.");
                 return;
             }
             reader = createInterface({
                 input: process.stdin,
                 output: process.stdout,
             });
-            const answer = (await reader.question("Choose a loadout: [1] Stable Daily Driver (recommended), [2] Power Boost, [3] Maximum Library, [4] Custom: ")).trim();
+            const answer = (await reader.question("Choose a loadout: [1] Stable Daily Driver (Loadout policy selection), [2] Power Boost, [3] Maximum Library, [4] Custom: ")).trim();
             mode =
                 answer === "2"
                     ? "power"
@@ -228,7 +228,7 @@ async function runSetup(options) {
         let riskApproved = Boolean(options.approveRisk);
         if (!approved) {
             if (!interactive) {
-                console.log("Preview complete; nothing was changed. Re-run with --yes to install this exact screened plan.");
+                console.log(formatCatalogApplyGuidance(Boolean(risky)));
                 return;
             }
             reader ??= createInterface({
@@ -258,7 +258,6 @@ async function runSetup(options) {
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: riskApproved,
         });
-        await recordInstalledProfile(prepared);
         console.log(`\nLoadout installed ${prepared.entries.length} repositories for ${prepared.agents.length} agent(s). Snapshot: ${snapshotId}`);
         console.log("Next: `loadout status`, `loadout optimize --project .`, or `loadout autopilot --yes` for opt-in daily read-only discovery and update checks.");
     }
@@ -266,7 +265,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.3.1";
+const LOADOUT_VERSION = "0.4.1";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -730,8 +729,8 @@ for (const workflow of ["activate", "optimize"]) {
     program
         .command(workflow)
         .description(workflow === "activate"
-        ? "Select and activate reviewed library skills for a project"
-        : "Scan a project and propose the best reviewed active-set additions")
+        ? "Select and activate inspected library skills for a project"
+        : "Scan a project and propose rule-selected inspected active-set additions")
         .option("--project <path>", "project directory to scan", ".")
         .option("--agents <ids>", "comma-separated agent ids")
         .option("--limit <count>", "maximum active skills per agent", "40")
@@ -1055,6 +1054,7 @@ program
         ? JSON.stringify({
             signals,
             recommendations,
+            recommendationBoundary: RECOMMENDATION_BOUNDARY,
             personalization: options.agent
                 ? {
                     agent: options.agent,
@@ -1066,7 +1066,7 @@ program
 });
 program
     .command("profiles")
-    .description("List tested Loadout profiles or inspect one profile")
+    .description("List Loadout policy profiles or inspect one profile")
     .argument("[name]", "profile name")
     .option("--json", "emit machine-readable JSON")
     .option("--apply-to <path>", "add the selected profile packages to a manifest")
@@ -1183,7 +1183,7 @@ program
     .description("Take ownership of one explicitly selected installed skill without changing its bytes")
     .argument("<skill>", "installed skill name, directory name, or exact path")
     .requiredOption("--agent <id>", "agent that owns the installed skill")
-    .option("--refresh-provenance", "rebuild the reviewed catalog skill index")
+    .option("--refresh-provenance", "rebuild the inspected catalog skill index")
     .option("--yes", "record ownership; otherwise show a dry-run plan")
     .option("--json", "emit machine-readable JSON")
     .action(async (skill, options) => {
@@ -1218,7 +1218,7 @@ program
     .description("Compare an installed or reviewed skill with evidence-related catalog alternatives without changing anything")
     .argument("<skill>", "installed skill name, directory name, or catalog package id")
     .option("--agent <id>", "select one installed agent when names are ambiguous")
-    .option("--refresh", "rebuild the reviewed catalog skill index")
+    .option("--refresh", "rebuild the inspected catalog skill index")
     .option("--offline", "never fetch; use the existing local index only")
     .option("--limit <count>", "maximum alternatives to show", "10")
     .option("--json", "emit the complete machine-readable comparison")
@@ -1559,6 +1559,7 @@ program
                 category: pkg.category,
                 tier: pkg.tier,
                 trustStage: catalogTrustStage(pkg),
+                evidenceLabel: formatCatalogTrustStage(catalogTrustStage(pkg)),
             },
             ranking: explainCatalogScore(pkg),
         }, null, 2));
@@ -1580,7 +1581,7 @@ program
         const updated = pkg.lastUpdatedAt
             ? ` — updated ${pkg.lastUpdatedAt.slice(0, 10)}`
             : "";
-        console.log(`${pkg.displayName} [${pkg.tier}; ${catalogTrustStage(pkg)}] ★${pkg.stars ?? "?"} — ${pkg.repository}${topics}${updated}`);
+        console.log(`${pkg.displayName} [${pkg.tier}; ${formatCatalogTrustStage(catalogTrustStage(pkg))}] ★${pkg.stars ?? "?"} — ${pkg.repository}${topics}${updated}`);
     }
     for (const failure of result.failures)
         console.error(`Warning: could not refresh ${failure.repository}: ${failure.error}`);
@@ -1648,7 +1649,7 @@ candidate
     .description("Convert a reviewed dossier into a catalog-record proposal; never edits the catalog")
     .argument("<dossier>", "persisted candidate dossier JSON")
     .requiredOption("--id <id>", "lowercase kebab-case catalog id")
-    .requiredOption("--category <category>", "reviewed catalog category")
+    .requiredOption("--category <category>", "inspected catalog category")
     .requiredOption("--platforms <ids>", "explicitly reviewed comma-separated platforms: windows,macos,linux")
     .option("--display-name <name>", "reviewed display name")
     .option("--description <text>", "reviewed description")
@@ -2590,13 +2591,12 @@ program
         });
         console.log(formatPreparedCatalogInstall(prepared));
         if (!options.yes) {
-            console.log("Preview complete; nothing was changed. Use --yes after reviewing to install this exact plan.");
+            console.log(formatCatalogApplyGuidance(prepared.entries.some((entry) => entry.safety.approvalRequired)));
             return;
         }
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: options.approveRisk,
         });
-        await recordInstalledProfile(prepared);
         console.log(`Installed ${prepared.entries.length} repositories as one transaction. Snapshot: ${snapshotId}`);
         return;
     }
@@ -2671,7 +2671,9 @@ program
         const chosen = options.snapshot ?? snapshotIds.at(-1);
         if (!chosen)
             throw new Error("No Loadout snapshots found");
-        await restoreSnapshot(await readSnapshot(chosen));
+        await restoreSnapshot(await readSnapshot(chosen), {
+            requireUnchangedPostMutationState: true,
+        });
         return chosen;
     });
     console.log(`Restored snapshot ${selected}`);
@@ -2716,7 +2718,6 @@ program
         profileSnapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: options.approveRisk,
         });
-        await recordInstalledProfile(prepared);
         if (!options.json)
             console.log(`Applied reviewed ${saved.mode} profile changes. Snapshot: ${profileSnapshotId}`);
         profile = await evaluateInstalledProfile(catalog);
@@ -2883,7 +2884,12 @@ for (const command of program.commands)
     if (HIDDEN_FROM_FIRST_SCREEN.has(command.name()))
         command._hidden = true;
 program.addHelpText("after", "\nStart here: `loadout guide` shows the safe everyday path. `loadout advanced` lists the retained maintainer and integration commands.\n");
-program.action(printBeginnerGuide);
+program.argument("[unknown-command]");
+program.action((unknownCommand) => {
+    if (unknownCommand)
+        throw new Error(`Unknown command '${unknownCommand}'. Run 'loadout --help' to list available commands.`);
+    printBeginnerGuide();
+});
 try {
     await recoverPendingTransactions();
     await program.parseAsync();

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/adapters.js

@@ -140,6 +140,16 @@ export function adapterCapabilities(agent) {
         throw new Error(`No adapter capability declaration for '${agent}'`);
     return found;
 }
+/**
+ * Return the display names of agents with an explicitly declared native skill
+ * directory. This is a filesystem-support boundary, not a claim about native
+ * application runtime behavior.
+ */
+export function supportedAdapterNames(adapters = ADAPTER_CAPABILITIES) {
+    return adapters
+        .filter((adapter) => adapter.components.skill === "native")
+        .map((adapter) => adapter.displayName);
+}
 /**
  * Produce a read-only native-skill plan for one agent.  This is deliberately
  * narrower than package normalization: adapters may only target a directory