loadout-ai 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.5.3 - 2026-07-21
+
+### Fixed
+
+- Include reviewed runtime-tool skills installed at official host-specific paths in
+  inventory, provenance, capacity, and health reporting. Graphify is now recognized
+  as Loadout-managed in both `~/.claude/skills` and Codex's `~/.codex/skills` target.
+- Report managed MCP server and runtime-tool counts in health, and warn when an
+  installed runtime tool's expected skill target disappears.
+- Give runtime-tool install snapshots meaningful labels instead of `managed change`.
+- Allow 30 seconds by default for a cold reviewed MCP connection handshake and make
+  MCP-only removal preview language accurately describe a removal plan.
+
 ## 0.5.2 - 2026-07-21
 
 ### Fixed

package/MASTER_PLAN.md

@@ -285,6 +285,15 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       counts. CLI-only TypeScript projects also reject browser-testing and
       Playwright false positives, and the default preview removes unexplained scores
       and duplicated delta output. Release as `0.5.2` before resuming activation.
+- [x] `P18-39 [TERRA]` Integrate reviewed runtime tools into the same inventory and
+      health truth as skill repositories. Founder testing proved Graphify installed
+      correctly for Claude Code and Codex, but the scanner counted Claude's target as
+      unmanaged and omitted Codex's official `~/.codex/skills` target because its
+      standard collection root is `~/.agents/skills`. Scan every registered runtime
+      target, attribute it to `runtime-tool:<id>`, count both host targets in health,
+      surface runtime/MCP totals and missing targets, label runtime snapshots, and
+      raise the default cold MCP handshake window to the tested 30 seconds. Release
+      as `0.5.3` before continuing Graphify removal and discovery/update acceptance.
 
 ### Release 0.3 lifecycle hardening
 

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.5.2`; 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.5.3`; 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.5.2
+npm install --global loadout-ai@0.5.3
 loadout --version
 loadout guide
 ```

package/dist/src/cli.js

@@ -263,7 +263,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.5.2";
+const LOADOUT_VERSION = "0.5.3";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -1007,7 +1007,7 @@ program
     const plan = await planRemove(packageId);
     console.log(JSON.stringify(plan, null, 2));
     if (!options.yes)
-        return console.log("Dry run only. Re-run with --yes to remove these files.");
+        return console.log("Dry run only. Re-run with --yes to apply this removal plan.");
     const snapshot = await applyRemove(plan, { force: options.force });
     console.log(`Removed ${packageId}. Snapshot: ${snapshot}`);
 });
@@ -2142,7 +2142,7 @@ program
     .option("--connect", "launch the exact pinned artifact and perform an MCP initialize handshake")
     .option("--credential <mapping>", "credential mapping NAME=env:VARIABLE or NAME=keychain:SERVICE (repeatable)", collectOption, [])
     .option("--credential-account <account>", "account for keychain mappings")
-    .option("--timeout <milliseconds>", "real connection timeout", "8000")
+    .option("--timeout <milliseconds>", "real connection timeout", "30000")
     .option("--approve-risk", "approve launching the reviewed pinned MCP artifact for --connect")
     .option("--json", "emit machine-readable JSON")
     .option("--no-key", "list recipes needing no separately billed AI/model API key")

package/dist/src/core/health.js

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import { managedFileReadPath } from "./active-set.js";
 import { detectAgents } from "./paths.js";
 import { readInstallState } from "./state.js";
 import { buildUpdatePlan } from "./update.js";
 import { codexMcpServerFingerprint } from "./codex-mcp.js";
+import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "./runtime-tools.js";
 async function drift(record, activations) {
     const changed = [];
     for (const file of record.files) {
@@ -35,18 +37,30 @@ async function mcpDrift(configPath, serverName, expected, configFormat = "json")
     }
 }
 export async function buildHealthReport(options = {}) {
-    const [agents, state, updates] = await Promise.all([
-        detectAgents(),
+    const [agents, state, updates, runtimeTools, runtimeTargets] = await Promise.all([
+        options.agents ? options.agents() : detectAgents(),
         readInstallState(),
         options.updates
             ? options.updates()
             : options.checkUpdates
                 ? buildUpdatePlan()
                 : Promise.resolve([]),
+        listInstalledRuntimeTools(),
+        listInstalledRuntimeToolSkillTargets(),
     ]);
     const drifted = (await Promise.all(state.installs.map((record) => drift(record, state.activations ?? [])))).flat();
     const driftedMcpServers = (await Promise.all((state.mcpInstalls ?? []).map((entry) => mcpDrift(entry.configPath, entry.serverName, entry.fingerprint, entry.configFormat)))).filter(Boolean).length;
     const findings = [];
+    const runtimeTargetPresence = await Promise.all(runtimeTargets.map(async (target) => {
+        try {
+            await readFile(join(target.path, "SKILL.md"));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    const missingRuntimeTargets = runtimeTargetPresence.filter((present) => !present).length;
     if (!agents.some((agent) => agent.installed))
         findings.push({
             level: "error",
@@ -81,6 +95,13 @@ export async function buildHealthReport(options = {}) {
             message: `${driftedMcpServers} managed MCP server entry or entries changed or disappeared outside Loadout.`,
             fix: "Review the MCP config, then synchronize or remove the owning package.",
         });
+    if (missingRuntimeTargets)
+        findings.push({
+            level: "warning",
+            code: "managed-runtime-target-drift",
+            message: `${missingRuntimeTargets} managed runtime-tool skill target(s) changed or disappeared.`,
+            fix: "Review the target, then remove and reinstall the owning runtime tool.",
+        });
     const available = updates.filter((update) => update.status === "update-available");
     if (available.length)
         findings.push({
@@ -99,9 +120,11 @@ export async function buildHealthReport(options = {}) {
             message: `${errors.length} update check(s) could not be completed.`,
             fix: "Check connectivity and retry.",
         });
-    const configured = state.installs.length > 0 || (state.mcpInstalls ?? []).length > 0;
+    const configured = state.installs.length > 0 ||
+        (state.mcpInstalls ?? []).length > 0 ||
+        runtimeTools.length > 0;
     const activeSkills = (state.activations ?? []).filter((entry) => entry.installationState === "installed" &&
-        entry.activationState === "active").length;
+        entry.activationState === "active").length + runtimeTargetPresence.filter(Boolean).length;
     const disabledSkills = (state.activations ?? []).filter((entry) => entry.installationState === "installed" &&
         entry.activationState === "disabled").length;
     const status = findings.some((finding) => finding.level === "error")
@@ -110,7 +133,10 @@ export async function buildHealthReport(options = {}) {
             ? "not-configured"
             : findings.some((finding) => finding.level === "warning")
                 ? "attention"
-                : activeSkills === 0 && disabledSkills > 0
+                : activeSkills === 0 &&
+                    disabledSkills > 0 &&
+                    (state.mcpInstalls ?? []).length === 0 &&
+                    runtimeTools.length === 0
                     ? "library-only"
                     : "healthy";
     return {
@@ -120,6 +146,8 @@ export async function buildHealthReport(options = {}) {
         installedPackages: state.installs.length,
         activeSkills,
         disabledSkills,
+        managedMcpServers: (state.mcpInstalls ?? []).length,
+        managedRuntimeTools: runtimeTools.length,
         updatesChecked: Boolean(options.updates || options.checkUpdates),
         updatesAvailable: available.length,
         driftedFiles: drifted.length,
@@ -137,7 +165,7 @@ export function formatHealthReport(report) {
                 : "✗";
     const lines = [
         `${icon} Loadout health: ${report.status === "not-configured" ? "not configured" : report.status === "library-only" ? "library ready (nothing active)" : report.status}`,
-        `Packages: ${report.installedPackages} managed; skills: ${report.activeSkills ?? 0} active, ${report.disabledSkills ?? 0} disabled; ${report.updatesChecked ? `${report.updatesAvailable} update(s)` : "updates not checked (use --updates)"}; ${report.driftedFiles} drifted file(s), ${report.driftedMcpServers} drifted MCP server(s)`,
+        `Packages: ${report.installedPackages} managed; skills: ${report.activeSkills ?? 0} active, ${report.disabledSkills ?? 0} disabled; MCP servers: ${report.managedMcpServers ?? 0}; runtime tools: ${report.managedRuntimeTools ?? 0}; ${report.updatesChecked ? `${report.updatesAvailable} update(s)` : "updates not checked (use --updates)"}; ${report.driftedFiles} drifted file(s), ${report.driftedMcpServers} drifted MCP server(s)`,
     ];
     for (const finding of report.findings)
         lines.push(`${finding.level === "ok" ? "✓" : finding.level === "error" ? "✗" : finding.level === "warning" ? "!" : "•"} ${finding.message}${finding.fix ? ` ${finding.fix}` : ""}`);

package/dist/src/core/mcp-recipes.js

@@ -148,7 +148,7 @@ export async function planMcpRecipe(recipeId, configPath, options = {}) {
     };
 }
 const MCP_PROTOCOL_VERSION = "2025-06-18";
-const DEFAULT_CONNECTION_TIMEOUT_MS = 8_000;
+const DEFAULT_CONNECTION_TIMEOUT_MS = 30_000;
 const DEFAULT_CONNECTION_OUTPUT_BYTES = 256 * 1024;
 const INITIALIZE_ID = "loadout-initialize";
 function validateConnectionBounds(timeoutMs, maxOutputBytes) {

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

@@ -222,6 +222,28 @@ export async function listInstalledRuntimeTools(stateHome = loadoutHome()) {
     const state = await readState(stateHome);
     return Object.keys(state.tools).sort();
 }
+/** Return agent skill targets owned by installed reviewed runtime tools. */
+export async function listInstalledRuntimeToolSkillTargets(options = {}) {
+    const state = await readState(options.stateHome ?? loadoutHome());
+    const home = options.home ?? userHome();
+    const platform = currentRecipePlatform(options.platform);
+    return Object.entries(state.tools).flatMap(([toolId, installed]) => {
+        const recipe = findRuntimeToolRecipe(toolId);
+        return installed.agents.flatMap((agent) => {
+            const target = recipe.targets[agent];
+            return target
+                ? [
+                    {
+                        toolId,
+                        packageId: `runtime-tool:${toolId}`,
+                        agent,
+                        path: resolveRuntimeRecipePath(home, target.path, platform),
+                    },
+                ]
+                : [];
+        });
+    });
+}
 async function writeState(state, stateHome) {
     await writeFileAtomically(statePath(stateHome), `${JSON.stringify(state, null, 2)}\n`);
 }
@@ -231,12 +253,10 @@ export function findRuntimeToolRecipe(id) {
         throw new Error(`Unknown runtime tool '${id}'. Available: ${REVIEWED_RUNTIME_TOOLS.map((item) => item.id).join(", ")}`);
     return recipe;
 }
-function currentRecipePlatform() {
-    if (process.platform === "darwin" ||
-        process.platform === "linux" ||
-        process.platform === "win32")
-        return process.platform;
-    throw new Error(`Runtime tool recipes do not support ${process.platform}`);
+function currentRecipePlatform(platform = process.platform) {
+    if (platform === "darwin" || platform === "linux" || platform === "win32")
+        return platform;
+    throw new Error(`Runtime tool recipes do not support ${platform}`);
 }
 function buildRuntimeToolCommands(recipe, runtimeRoot, agents, platform, action) {
     if (action === "remove")
@@ -425,7 +445,9 @@ export async function applyRuntimeToolPlan(plan, options) {
         const snapshotRoots = plan.recipe.snapshotRoots.flatMap((root) => root === "{runtimeRoot}"
             ? [plan.runtimeRoot]
             : plan.agents.map((agent) => agent.target));
-        snapshot = await createSnapshot(snapshotRoots);
+        snapshot = await createSnapshot(snapshotRoots, {
+            label: `install runtime tool ${plan.recipe.displayName}`,
+        });
         const runner = options.runner ?? defaultRunner;
         const env = runtimeEnvironment(plan);
         const healthCheckStart = plan.commands.length - plan.recipe.healthChecks.length;

package/dist/src/core/skill-inventory.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, readFile, readdir } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
 import { readInstallState } from "./state.js";
+import { listInstalledRuntimeToolSkillTargets, } from "./runtime-tools.js";
 const MAX_SCAN_DEPTH = 6;
 export const RECOMMENDED_ACTIVE_SKILLS = 30;
 function cleanFrontmatterValue(value) {
@@ -17,7 +18,10 @@ function isInside(root, candidate) {
     const path = relative(resolve(root), resolve(candidate));
     return path === "" || (!path.startsWith("..") && !path.startsWith(sep));
 }
-function owningPackage(skillRoot, agent, records, activations) {
+function owningPackage(skillRoot, agent, records, activations, runtimeTargets) {
+    const runtime = runtimeTargets.find((target) => target.agent === agent && isInside(target.path, skillRoot));
+    if (runtime)
+        return runtime.packageId;
     const active = activations.find((record) => record.agent === agent &&
         record.activationState === "active" &&
         record.installationState === "installed" &&
@@ -29,8 +33,15 @@ function owningPackage(skillRoot, agent, records, activations) {
             activation.agent === agent) &&
         record.files.some((file) => isInside(skillRoot, file.path)))?.packageId;
 }
-async function scanAgentSkills(agent, records, activations) {
-    const root = resolve(agent.skillsDirectory);
+async function scanAgentSkills(agent, records, activations, runtimeTargets) {
+    const primaryRoot = resolve(agent.skillsDirectory);
+    const roots = [
+        primaryRoot,
+        ...runtimeTargets
+            .filter((target) => target.agent === agent.id)
+            .map((target) => resolve(target.path))
+            .filter((target) => !isInside(primaryRoot, target)),
+    ];
     const skills = [];
     const warnings = [];
     async function visit(directory, depth) {
@@ -60,7 +71,7 @@ async function scanAgentSkills(agent, records, activations) {
             try {
                 const path = join(directory, "SKILL.md");
                 const content = await readFile(path, "utf8");
-                const packageId = owningPackage(directory, agent.id, records, activations);
+                const packageId = owningPackage(directory, agent.id, records, activations, runtimeTargets);
                 const sourceHints = [
                     ...new Set([
                         ...content.matchAll(/https?:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
@@ -102,7 +113,8 @@ async function scanAgentSkills(agent, records, activations) {
                 await visit(join(directory, child.name), depth + 1);
         }
     }
-    await visit(root, 0);
+    for (const root of [...new Set(roots)])
+        await visit(root, 0);
     return {
         skills: skills.sort((left, right) => left.path.localeCompare(right.path)),
         warnings,
@@ -141,8 +153,11 @@ function duplicateGroups(skills) {
  * safety verdict and no files are changed by this scan.
  */
 export async function scanInstalledSkills(agents) {
-    const state = await readInstallState();
-    const scans = await Promise.all(agents.map((agent) => scanAgentSkills(agent, state.installs, state.activations ?? [])));
+    const [state, runtimeTargets] = await Promise.all([
+        readInstallState(),
+        listInstalledRuntimeToolSkillTargets(),
+    ]);
+    const scans = await Promise.all(agents.map((agent) => scanAgentSkills(agent, state.installs, state.activations ?? [], runtimeTargets)));
     const skills = scans.flatMap((scan) => scan.skills);
     const warnings = scans.flatMap((scan) => scan.warnings);
     const summaries = agents.map((agent, index) => {
@@ -157,6 +172,7 @@ export async function scanInstalledSkills(agents) {
             managed,
             unmanaged: entries.length - managed,
             overRecommendedLimit: entries.length > RECOMMENDED_ACTIVE_SKILLS,
+            runtimeToolTargets: runtimeTargets.filter((target) => target.agent === agent.id).length,
         };
     });
     for (const summary of summaries.filter((item) => item.overRecommendedLimit))
@@ -185,7 +201,7 @@ export function formatInstalledSkillInventory(report) {
         "",
     ];
     for (const agent of report.agents)
-        lines.push(`${agent.detected ? "✓" : "○"} ${agent.displayName}: ${agent.total} skill(s) (${agent.managed} managed, ${agent.unmanaged} unmanaged) — ${agent.directory}`);
+        lines.push(`${agent.detected ? "✓" : "○"} ${agent.displayName}: ${agent.total} skill(s) (${agent.managed} managed, ${agent.unmanaged} unmanaged)${agent.runtimeToolTargets ? `, including ${agent.runtimeToolTargets} runtime-tool skill(s)` : ""} — ${agent.directory}`);
     for (const warning of report.warnings)
         lines.push(`! ${warning}`);
     lines.push("", "Read-only scan complete. Unmanaged content was not changed or judged automatically.");

package/docs/USER_TEST_GUIDE.md

@@ -183,7 +183,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.5.2` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.5.3` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,

package/package.json

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