loadout-ai 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.2 - 2026-07-17
+
+### Fixed
+
+- Reconcile Stable and Power to their exact managed skill sets instead of leaving skills from the previous profile active.
+- Preview every managed skill that profile setup will retire and reject an apply if managed state changed after the preview.
+- Snapshot retired skills in the same transaction, preserve unmanaged skills, and refuse to retire locally changed managed content.
+
+## 0.2.1 - 2026-07-17
+
+### Fixed
+
+- Make Stable and Power setup safe to rerun when Loadout already owns some target skills.
+- Preserve unmanaged skills and refuse to replace managed skills that changed outside Loadout.
+- Verify every replacement byte and keep mixed existing/new-agent installs rollback-safe.
+
 ## 0.2.0 - 2026-07-17
 
 ### Added

package/MASTER_PLAN.md

@@ -1023,13 +1023,12 @@ universal or permanent truth.
       `NOASSERTION` records, before distribution.
 - [ ] `P12-31 [TERRA]` Publish `loadout-ai` to npm and run clean-machine package tests
       from outside the repository on macOS, Windows, Linux, and Node 20/22.
-  - Partial: `loadout-ai@0.1.2` was published publicly on 2026-07-16 while the GitHub
-    repository remained private. Registry metadata, `npx` version/help, and a real
-    read-only Stable preview passed outside the source directory. Patch `0.1.2`
-    adds Codex Desktop detection through its existing `~/.codex` home when the
-    standalone `codex` executable is absent from the user's shell PATH. CI contains an
-    opt-in OS/Node matrix and OIDC/provenance release workflow; clean independent-user
-    installs on Windows/macOS/Linux remain required.
+  - Partial: `loadout-ai@0.2.0` was published publicly on 2026-07-17 while the GitHub
+    repository remained private. Registry version/integrity, a clean external npm
+    install, version/help, 50-record catalog coverage, and the real disposable
+    Superpowers install/rollback demo pass on macOS. Hosted matrix evidence already
+    covers Windows/macOS/Linux and Node 20/22; clean independent-user installs on
+    Windows and Linux remain required.
 - [ ] `P12-32 [HUMAN]` Run moderated founder testing on the real Claude and Codex
       profiles with snapshots and explicit rollback checkpoints.
   - Partial 2026-07-16: the founder ran the published npm CLI against the real macOS
@@ -1170,7 +1169,7 @@ universal or permanent truth.
     1,000 on-disk skills at a 1.29-second p95 on macOS/Node 23.
 - [ ] `P15-06 [HUMAN]` Approve public repository visibility, complete the six
       `NOASSERTION` license decisions, authenticate npm, and publish `loadout-ai`.
-  - Partial 2026-07-16: npm authentication and the public `loadout-ai@0.1.2`
+  - Partial 2026-07-17: npm authentication and the public `loadout-ai@0.2.0`
     publication succeeded. Repository visibility remains private at the owner's
     request, and the six root-level `NOASSERTION` decisions remain a human release
     gate; therefore this combined item is not ticked.
@@ -1601,6 +1600,10 @@ accident.
   - Repeat the safe no-key journey with Claude, then collect one Windows and one Linux
     external session. Convert every reproducible failure into a regression test before
     public-release claims.
+  - Partial 2026-07-17: the registry and clean external macOS install are verified for
+    `0.2.0`; the published CLI loads the complete command surface, reports all 50
+    catalog records, and completes its disposable install/rollback demo. Real founder
+    Stable/Power/Maximum and Claude-profile exercises remain deliberately pending.
 - [x] `P17-09 [TERRA implementation, LUNA copy review]` Make Power resilient and
       explain the product in beginner language before the `0.2.0` release.
   - Power now quarantines a rejected selected skill while retaining safe selected

package/dist/src/cli.js

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

package/dist/src/core/catalog-install.js

@@ -1,7 +1,7 @@
 import { loadEffectiveCatalog } from "./catalog.js";
 import { detectAgents } from "./paths.js";
 import { isStableSkillSelected, isPowerSkillSelected, resolveCatalogProfile, } from "./profiles.js";
-import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, installedAgents, } from "./install.js";
+import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, installedAgents, planManagedProfileReconciliation, } from "./install.js";
 import { fetchRepositorySnapshot, } from "./source.js";
 import { analyzeInstallPlanSafety, } from "./safety.js";
 import { formatModelApiAccess } from "./access.js";
@@ -175,6 +175,14 @@ export async function prepareCatalogInstall(selection, options = {}) {
         });
         return false;
     });
+    const reconciliation = selection.mode === "maximum"
+        ? {
+            obsoleteActivationKeys: [],
+            obsoletePackageIds: [],
+            obsoleteTargets: [],
+            obsoleteUnits: [],
+        }
+        : await planManagedProfileReconciliation(usableEntries);
     return {
         selection,
         resolution,
@@ -183,6 +191,7 @@ export async function prepareCatalogInstall(selection, options = {}) {
         skipped,
         collisions,
         access: options.access ?? { modelApis: [] },
+        reconciliation,
     };
 }
 export function formatPreparedCatalogInstall(prepared) {
@@ -194,6 +203,7 @@ export function formatPreparedCatalogInstall(prepared) {
     const explicit = prepared.skipped.filter((item) => item.kind === "explicit-setup");
     const failures = prepared.skipped.filter((item) => item.kind === "preparation-failed");
     const quarantined = prepared.skipped.filter((item) => item.kind === "quarantined");
+    const retired = prepared.reconciliation?.obsoleteUnits ?? [];
     const lines = [
         `Loadout: ${prepared.selection.mode === "maximum" ? "Maximum Library" : prepared.selection.mode === "power" ? "Power Boost" : prepared.selection.mode === "stable" ? "Stable Boost" : "Custom"}`,
         `Detected agents: ${prepared.agents.map((agent) => agent.displayName).join(", ")}`,
@@ -211,6 +221,11 @@ export function formatPreparedCatalogInstall(prepared) {
         lines.push(`Quarantined invalid skill units: ${quarantined.length} (safe siblings remain available)`);
     if (prepared.collisions.length)
         lines.push(`Overlapping skill targets resolved: ${prepared.collisions.length} lower-ranked duplicate directories deferred`);
+    if (retired.length) {
+        lines.push(`Profile reconciliation: ${retired.length} active managed skill${retired.length === 1 ? "" : "s"} will be retired from the selected agents.`);
+        for (const item of retired)
+            lines.push(`Retire ${item.packageId}${item.unitId ? `/${item.unitId}` : ""} from ${item.agent}`);
+    }
     if (risky.length)
         lines.push(`Additional risk approval required: ${risky.map((entry) => entry.package.id).join(", ")}`);
     for (const warning of prepared.resolution.warnings)
@@ -230,5 +245,11 @@ export async function applyPreparedCatalogInstall(prepared, options = {}) {
         throw new Error(`Additional risk approval is required for: ${risky.map((entry) => entry.package.id).join(", ")}. Review the plan, then use --approve-risk.`);
     return prepared.selection.mode === "maximum"
         ? applySkillLibraryBatch(prepared.entries)
-        : applySkillInstallBatch(prepared.entries);
+        : applySkillInstallBatch(prepared.entries, [], {
+            replaceManagedTargets: true,
+            reconcileManagedTargets: true,
+            ...(prepared.reconciliation
+                ? { expectedReconciliation: prepared.reconciliation }
+                : {}),
+        });
 }

package/dist/src/core/install.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
 import { cp, lstat, rm } from "node:fs/promises";
-import { basename, dirname, join, posix, relative, win32 } from "node:path";
+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, } from "./state.js";
+import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, writeInstallState, } from "./state.js";
 import { runMutationTransaction } from "./transaction.js";
 export function installedAgents(agents, requested) {
     const available = agents.filter((agent) => agent.installed);
@@ -17,6 +17,100 @@ export function installedAgents(agents, requested) {
     }
     return selected;
 }
+function relativeHashes(root, files) {
+    return files
+        .filter((file) => isInside(root, file.path))
+        .map((file) => ({
+        path: relative(root, file.path),
+        sha256: file.sha256,
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+function isInside(root, path) {
+    const child = relative(root, path);
+    return child !== "" && !child.startsWith("..") && !isAbsolute(child);
+}
+function activationKey(record) {
+    return `${record.packageId}\0${record.agent}\0${record.unitId ?? ""}`;
+}
+async function assertManagedTargetUnchanged(target, owner) {
+    const expected = relativeHashes(target, owner?.files ?? []);
+    const actual = relativeHashes(target, await hashDirectory(target));
+    if (!expected.length || JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`Installation refuses to replace drifted managed skill target: ${target}`);
+}
+export async function planManagedProfileReconciliation(entries) {
+    const state = await readInstallState();
+    const requestedAgents = new Set(entries.flatMap((entry) => entry.plan.targetAgents));
+    const desiredTargets = new Set(entries.flatMap((entry) => entry.plan.files.map((file) => file.target)));
+    const obsolete = [];
+    for (const activation of state.activations ?? []) {
+        if (!requestedAgents.has(activation.agent) ||
+            activation.installationState !== "installed" ||
+            activation.activationState !== "active")
+            continue;
+        const staleTargets = activation.targets.filter((target) => !desiredTargets.has(target.activePath));
+        if (!staleTargets.length)
+            continue;
+        if (staleTargets.length !== activation.targets.length)
+            throw new Error(`Profile reconciliation refuses a partially selected managed unit: ${activation.packageId}/${activation.unitId ?? "skill"}`);
+        const owner = state.installs.find((record) => record.packageId === activation.packageId);
+        for (const target of staleTargets)
+            await assertManagedTargetUnchanged(target.activePath, owner);
+        obsolete.push(activation);
+    }
+    return {
+        obsoleteActivationKeys: obsolete.map(activationKey),
+        obsoletePackageIds: [...new Set(obsolete.map((item) => item.packageId))],
+        obsoleteTargets: [
+            ...new Set(obsolete.flatMap((item) => item.targets.map((target) => target.activePath))),
+        ],
+        obsoleteUnits: obsolete.map((item) => ({
+            packageId: item.packageId,
+            agent: item.agent,
+            ...(item.unitId ? { unitId: item.unitId } : {}),
+        })),
+    };
+}
+function reconciliationSignature(reconciliation) {
+    return JSON.stringify({
+        keys: [...reconciliation.obsoleteActivationKeys].sort(),
+        targets: [...reconciliation.obsoleteTargets].sort(),
+    });
+}
+async function recordManagedProfileReconciliation(reconciliation) {
+    if (!reconciliation.obsoleteActivationKeys.length)
+        return;
+    const obsoleteKeys = new Set(reconciliation.obsoleteActivationKeys);
+    const affectedPackages = new Set(reconciliation.obsoletePackageIds);
+    const state = await readInstallState();
+    state.activations = (state.activations ?? []).filter((record) => !obsoleteKeys.has(activationKey(record)));
+    state.installs = state.installs.flatMap((install) => {
+        if (!affectedPackages.has(install.packageId))
+            return [install];
+        const remaining = (state.activations ?? []).filter((record) => record.packageId === install.packageId &&
+            record.installationState === "installed");
+        if (!remaining.length)
+            return [];
+        const roots = remaining.flatMap((record) => record.targets.map((target) => target.activePath));
+        return [
+            {
+                ...install,
+                targetAgents: [...new Set(remaining.map((record) => record.agent))],
+                files: install.files.filter((file) => roots.some((root) => isInside(root, file.path))),
+            },
+        ];
+    });
+    await writeInstallState(state);
+}
+async function assertExactDirectoryCopy(source, target, label) {
+    const [expected, actual] = await Promise.all([
+        hashDirectory(source).then((files) => relativeHashes(source, files)),
+        hashDirectory(target).then((files) => relativeHashes(target, files)),
+    ]);
+    if (JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`${label} for ${target}`);
+}
 async function assertActiveTargetsUnoccupied(plans, options = {}) {
     const occupied = [];
     for (const target of [
@@ -35,26 +129,36 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
         }
     if (occupied.length && options.allowManagedReplacement) {
         const state = await readInstallState();
-        const allowed = new Set(plans.flatMap((plan) => {
+        const allowed = new Map();
+        for (const plan of plans) {
             const install = state.installs.find((record) => record.packageId === plan.packageId);
             const packageActivations = (state.activations ?? []).filter((record) => record.packageId === plan.packageId);
-            const active = packageActivations.length === 0 ||
-                packageActivations.some((record) => record.installationState === "installed" &&
-                    record.activationState === "active");
-            if (!install || !active)
-                return [];
+            if (!install)
+                continue;
+            const activeTargets = new Set(packageActivations
+                .filter((record) => record.installationState === "installed" &&
+                record.activationState === "active")
+                .flatMap((record) => record.targets.map((target) => target.activePath)));
             const recorded = install.files
                 .filter((file) => basename(file.path) === "SKILL.md")
-                .map((file) => dirname(file.path));
+                .map((file) => dirname(file.path))
+                .filter((target) => packageActivations.length === 0 || activeTargets.has(target));
             const legacy = packageActivations.length
                 ? []
                 : plan.files
                     .map((file) => file.target)
                     .filter((target) => basename(target) === plan.packageId);
-            return [...recorded, ...legacy];
-        }));
-        if (occupied.every((target) => allowed.has(target)))
+            for (const target of [...recorded, ...legacy])
+                if (plan.files.some((file) => file.target === target))
+                    allowed.set(target, install);
+        }
+        if (occupied.every((target) => allowed.has(target))) {
+            for (const target of occupied) {
+                const owner = allowed.get(target);
+                await assertManagedTargetUnchanged(target, owner);
+            }
             return;
+        }
     }
     if (occupied.length)
         throw new Error(`Installation refuses ${occupied.length} occupied skill target(s); scan, compare, or adopt them first. First target: ${occupied[0]}`);
@@ -106,20 +210,7 @@ export async function applySkillInstall(plan, metadata, options = {}) {
         await applySkillPlan(freshPlan);
         if (options.replaceManagedTargets)
             for (const file of freshPlan.files) {
-                const expected = (await hashDirectory(file.source))
-                    .map((entry) => ({
-                    path: relative(file.source, entry.path),
-                    sha256: entry.sha256,
-                }))
-                    .sort((left, right) => left.path.localeCompare(right.path));
-                const actual = (await hashDirectory(file.target))
-                    .map((entry) => ({
-                    path: relative(file.target, entry.path),
-                    sha256: entry.sha256,
-                }))
-                    .sort((left, right) => left.path.localeCompare(right.path));
-                if (JSON.stringify(actual) !== JSON.stringify(expected))
-                    throw new Error(`Exact update copy verification failed for ${file.target}`);
+                await assertExactDirectoryCopy(file.source, file.target, "Exact update copy verification failed");
             }
         await recordInstall(freshPlan, snapshot.id, metadata);
         await options.verifyBeforeCommit?.(snapshot.id);
@@ -127,7 +218,7 @@ export async function applySkillInstall(plan, metadata, options = {}) {
     return applied.snapshotId;
 }
 /** Apply all selected packages as one filesystem transaction and one state update. */
-export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
+export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], options = {}) {
     if (!entries.length)
         throw new Error("Installation batch is empty");
     const conflicts = detectInstallConflicts(entries.map((entry) => entry.plan));
@@ -135,7 +226,19 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
     if (blocking.length)
         throw new Error(`Installation blocked by conflicts: ${blocking.map((item) => item.message).join("; ")}`);
     const applied = await runMutationTransaction(async () => {
-        await assertActiveTargetsUnoccupied(entries.map((entry) => entry.plan));
+        const reconciliation = options.reconcileManagedTargets
+            ? await planManagedProfileReconciliation(entries)
+            : {
+                obsoleteActivationKeys: [],
+                obsoletePackageIds: [],
+                obsoleteTargets: [],
+                obsoleteUnits: [],
+            };
+        if (options.expectedReconciliation &&
+            reconciliationSignature(reconciliation) !==
+                reconciliationSignature(options.expectedReconciliation))
+            throw new Error("Profile reconciliation refused because managed state changed after preview; prepare the plan again.");
+        await assertActiveTargetsUnoccupied(entries.map((entry) => entry.plan), { allowManagedReplacement: options.replaceManagedTargets });
         for (const entry of entries) {
             entry.plan.conflicts = [
                 ...(entry.plan.conflicts ?? []),
@@ -156,13 +259,26 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
                 ...entries.flatMap((entry) => entry.plan.files.map((file) => file.target)),
                 installStatePath(),
                 ...extraSnapshotPaths,
+                ...reconciliation.obsoleteTargets,
             ],
-            value: entries,
+            value: { entries, reconciliation },
         };
-    }, async (freshEntries, snapshot) => {
+    }, async ({ entries: freshEntries, reconciliation }, snapshot) => {
+        for (const target of reconciliation.obsoleteTargets)
+            await rm(target, { recursive: true, force: true });
+        if (options.replaceManagedTargets)
+            for (const target of [
+                ...new Set(freshEntries.flatMap((entry) => entry.plan.files.map((file) => file.target))),
+            ])
+                await rm(target, { recursive: true, force: true });
         for (const entry of freshEntries)
             await applySkillPlan(entry.plan);
+        if (options.replaceManagedTargets)
+            for (const entry of freshEntries)
+                for (const file of entry.plan.files)
+                    await assertExactDirectoryCopy(file.source, file.target, "Exact setup copy verification failed");
         await recordInstallBatch(freshEntries, snapshot.id);
+        await recordManagedProfileReconciliation(reconciliation);
     });
     return applied.snapshotId;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",