loadout-ai 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.3 - 2026-07-17
+
+### Fixed
+
+- Validate large rollback snapshots in linear, constant-stack time so project-aware activation can safely snapshot large reviewed skills.
+- Preserve strict malformed-base64 rejection without relying on a stack-intensive regular expression.
+- Rewrite every generated Graphify top-level lookup, repair, and optional Gemini install to the reviewed hashed artifact instead of leaving unpinned package fallbacks.
+
+## 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

package/dist/src/cli.js

@@ -262,7 +262,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.2.1";
+const LOADOUT_VERSION = "0.2.3";
 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)
@@ -232,5 +247,9 @@ export async function applyPreparedCatalogInstall(prepared, options = {}) {
         ? applySkillLibraryBatch(prepared.entries)
         : applySkillInstallBatch(prepared.entries, [], {
             replaceManagedTargets: true,
+            reconcileManagedTargets: true,
+            ...(prepared.reconciliation
+                ? { expectedReconciliation: prepared.reconciliation }
+                : {}),
         });
 }

package/dist/src/core/install.js

@@ -4,7 +4,7 @@ import { basename, dirname, isAbsolute, join, posix, relative, win32, } from "no
 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);
@@ -19,16 +19,90 @@ export function installedAgents(agents, requested) {
 }
 function relativeHashes(root, files) {
     return files
-        .filter((file) => {
-        const child = relative(root, file.path);
-        return child !== "" && !child.startsWith("..") && !isAbsolute(child);
-    })
+        .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)),
@@ -81,11 +155,7 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
         if (occupied.every((target) => allowed.has(target))) {
             for (const target of occupied) {
                 const owner = allowed.get(target);
-                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}`);
+                await assertManagedTargetUnchanged(target, owner);
             }
             return;
         }
@@ -156,6 +226,18 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
     if (blocking.length)
         throw new Error(`Installation blocked by conflicts: ${blocking.map((item) => item.message).join("; ")}`);
     const applied = await runMutationTransaction(async () => {
+        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 = [
@@ -177,10 +259,13 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
                 ...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))),
@@ -193,6 +278,7 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
                 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/dist/src/core/runtime-tool-recipe.js

@@ -118,7 +118,14 @@ const generatedFilesSchema = z
         .object({
         fileExtension: z.string().regex(/^\.[A-Za-z0-9]+$/),
         from: nonControlTextSchema,
-        to: nonControlTextSchema.refine((value) => !/[{}]/u.test(value.replaceAll("{artifactRequirement}", "")), "unknown rewrite template variable"),
+        to: nonControlTextSchema.refine((value) => {
+            const rendered = [
+                "{artifactRequirement}",
+                "{artifactUrl}",
+                "{artifactSha256}",
+            ].reduce((current, placeholder) => current.replaceAll(placeholder, ""), value);
+            return !/[{}]/u.test(rendered);
+        }, "unknown rewrite template variable"),
         mustEliminate: z.boolean(),
     })
         .strict()),
@@ -306,6 +313,8 @@ export function runtimeArtifactRequirement(recipe) {
 export function renderRuntimeRecipeValue(value, recipe) {
     return value
         .replaceAll("{artifactRequirement}", runtimeArtifactRequirement(recipe))
+        .replaceAll("{artifactUrl}", recipe.artifactUrl)
+        .replaceAll("{artifactSha256}", recipe.artifactSha256)
         .replaceAll("{version}", recipe.version);
 }
 /** Resolve reviewed path segments without ever accepting a recipe-owned root. */

package/dist/src/core/runtime-tools.js

@@ -162,6 +162,24 @@ export const GRAPHIFY_RECIPE = deepFreeze(parseRuntimeToolRecipe({
                 to: "--from '{artifactRequirement}'",
                 mustEliminate: true,
             },
+            {
+                fileExtension: ".md",
+                from: "install --upgrade graphifyy",
+                to: "install '{artifactRequirement}' --exclude-newer 2026-07-17T00:00:00Z",
+                mustEliminate: true,
+            },
+            {
+                fileExtension: ".md",
+                from: "pip install graphifyy",
+                to: "pip install '{artifactRequirement}'",
+                mustEliminate: true,
+            },
+            {
+                fileExtension: ".md",
+                from: "pip install 'graphifyy[gemini]'",
+                to: "pip install 'graphifyy[gemini] @ {artifactUrl}#sha256={artifactSha256}'",
+                mustEliminate: true,
+            },
         ],
     },
     guarantees: [
@@ -169,7 +187,7 @@ export const GRAPHIFY_RECIPE = deepFreeze(parseRuntimeToolRecipe({
         "exact top-level wheel URL and SHA-256; dependency uploads bounded by the reviewed cutoff",
         "no API keys or provider credentials inherited by installer subprocesses",
         "agent skill targets and isolated runtime are snapshotted for rollback/removal",
-        "generated runtime lookup is rewritten to the same pinned Graphify artifact",
+        "generated top-level Graphify lookups and repair commands are rewritten to the same pinned artifact",
     ],
 }));
 export const REVIEWED_RUNTIME_TOOLS = [GRAPHIFY_RECIPE];

package/dist/src/core/snapshot.js

@@ -205,6 +205,19 @@ export function validateSnapshot(value) {
     return value;
 }
 function isCanonicalBase64(value) {
-    return (value.length % 4 === 0 &&
-        /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value));
+    if (value.length % 4 !== 0)
+        return false;
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    const contentLength = value.length - padding;
+    for (let index = 0; index < contentLength; index += 1) {
+        const code = value.charCodeAt(index);
+        const valid = (code >= 65 && code <= 90) ||
+            (code >= 97 && code <= 122) ||
+            (code >= 48 && code <= 57) ||
+            code === 43 ||
+            code === 47;
+        if (!valid)
+            return false;
+    }
+    return value.slice(contentLength) === "=".repeat(padding);
 }

package/package.json

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