loadout-ai 0.1.0

package/dist/src/core/sync.js

@@ -0,0 +1,348 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { loadEffectiveCatalog } from "./catalog.js";
+import { installedAgents } from "./install.js";
+import { orderManifestPackages, readManifest, writeLockfile, } from "./manifest.js";
+import { detectAgents, userHome } from "./paths.js";
+import { fetchGitSnapshot, fetchRepositorySnapshot } from "./source.js";
+import { addRootFileExports, buildUniversalPackagePlan } from "./components.js";
+import { analyzeInstallPlanSafety, } from "./safety.js";
+import { fetchRemoteRegistryPackage, packPackage, resolveRegistryPackage, } from "./registry.js";
+import { discoverMcpManifests, planMcpConfigBatch, writeMcpConfigPlan, } from "./mcp.js";
+import { applySkillPlan, detectInstallConflicts } from "./skills.js";
+import { installStatePath, readInstallState, recordInstallTransaction, } from "./state.js";
+import { runMutationTransaction } from "./transaction.js";
+function registrySourceKey(source) {
+    if (source.type === "registry")
+        return `local:${source.name}@${source.version}`;
+    if (source.type === "remote-registry")
+        return `${source.registry}:${source.name}@${source.version}`;
+    return undefined;
+}
+function dependencySource(parent, name, version) {
+    if (parent.type === "registry")
+        return { type: "registry", name, version };
+    if (parent.type === "remote-registry")
+        return {
+            type: "remote-registry",
+            registry: parent.registry,
+            name,
+            version,
+        };
+    throw new Error("Only registry packages can resolve package-owned dependencies");
+}
+async function expandRegistryDependencies(manifest) {
+    const explicit = new Map(manifest.packages.map((pkg) => [pkg.id, pkg]));
+    const expanded = new Map();
+    const visiting = new Set();
+    const packageCache = new Map();
+    const requestedVersions = new Map();
+    async function visit(input, chain) {
+        const key = registrySourceKey(input.source);
+        if (!key) {
+            if (!expanded.has(input.id))
+                expanded.set(input.id, input);
+            return;
+        }
+        if (visiting.has(key))
+            throw new Error(`Registry dependency cycle: ${[...chain, input.id].join(" -> ")}`);
+        const existing = expanded.get(input.id);
+        if (existing) {
+            if (JSON.stringify(existing.source) !== JSON.stringify(input.source))
+                throw new Error(`Registry dependency id '${input.id}' resolves to conflicting sources`);
+            const agents = existing.agents === undefined || input.agents === undefined
+                ? undefined
+                : [...new Set([...existing.agents, ...input.agents])];
+            expanded.set(input.id, {
+                ...existing,
+                ...(agents ? { agents } : { agents: undefined }),
+            });
+            return;
+        }
+        visiting.add(key);
+        let packed = packageCache.get(key);
+        if (!packed) {
+            const source = await resolvePackage(input);
+            packed = await packPackage(source.path);
+            packageCache.set(key, packed);
+        }
+        const dependencies = Object.entries({
+            ...(packed.descriptor.dependencies ?? {}),
+            ...(input.includeDevDependencies
+                ? (packed.descriptor.devDependencies ?? {})
+                : {}),
+        }).sort(([left], [right]) => left.localeCompare(right));
+        const dependencyIds = [];
+        for (const [name, version] of dependencies) {
+            const previous = requestedVersions.get(name);
+            if (previous && previous !== version)
+                throw new Error(`Registry dependency version conflict for '${name}': ${previous} versus ${version}`);
+            requestedVersions.set(name, version);
+            const source = dependencySource(input.source, name, version);
+            const configured = explicit.get(name);
+            if (configured &&
+                JSON.stringify(configured.source) !== JSON.stringify(source))
+                throw new Error(`Registry dependency '${name}@${version}' conflicts with explicitly configured package '${name}'`);
+            await visit(configured ?? {
+                id: name,
+                source,
+                ...(input.agents ? { agents: input.agents } : {}),
+            }, [...chain, input.id]);
+            dependencyIds.push(name);
+        }
+        visiting.delete(key);
+        const dependsOn = [
+            ...new Set([...(input.dependsOn ?? []), ...dependencyIds]),
+        ];
+        expanded.set(input.id, {
+            ...input,
+            ...(dependsOn.length ? { dependsOn } : {}),
+        });
+    }
+    for (const pkg of manifest.packages)
+        await visit(pkg, []);
+    return { ...manifest, packages: [...expanded.values()] };
+}
+function policyViolations(manifest, packages) {
+    const violations = [];
+    const blockedDomains = new Set((manifest.policy?.blockedDomains ?? []).map((domain) => domain.toLowerCase()));
+    const blockedCommands = new Set((manifest.policy?.blockedCommands ?? []).map((command) => command.toLowerCase()));
+    const allowPackages = new Set(manifest.policy?.allowPackages ?? []);
+    const allowRepositories = new Set((manifest.policy?.allowRepositories ?? []).map((repository) => repository.toLowerCase()));
+    const deniedPackages = new Set(manifest.policy?.deniedPackages ?? []);
+    const deniedRepositories = new Set((manifest.policy?.deniedRepositories ?? []).map((repository) => repository.toLowerCase()));
+    for (const entry of packages) {
+        const packageId = entry.plan.packageId;
+        const repository = entry.metadata?.repository?.toLowerCase();
+        if (allowPackages.size && !allowPackages.has(packageId))
+            violations.push(`${packageId} is not on the package allowlist`);
+        if (allowRepositories.size &&
+            (!repository || !allowRepositories.has(repository)))
+            violations.push(`${packageId} is not on the repository allowlist`);
+        if (deniedPackages.has(packageId))
+            violations.push(`${packageId} is on the package denylist`);
+        if (repository && deniedRepositories.has(repository))
+            violations.push(`${packageId} is on the repository denylist`);
+        for (const finding of entry.safety.findings) {
+            if (finding.category === "domain")
+                for (const domain of finding.names ?? [])
+                    if (blockedDomains.has(domain.toLowerCase()))
+                        violations.push(`${entry.plan.packageId} references blocked domain '${domain}'`);
+        }
+        for (const file of entry.plan.files) {
+            const name = file.source
+                .split(/[\\/]/)
+                .at(-1)
+                ?.replace(/\.[^.]+$/, "")
+                .toLowerCase();
+            if (name && blockedCommands.has(name))
+                violations.push(`${entry.plan.packageId} contains blocked command '${name}'`);
+        }
+    }
+    return [...new Set(violations)];
+}
+async function resolvePackage(pkg) {
+    if (pkg.source.type === "local")
+        return { path: resolve(pkg.source.path) };
+    if (pkg.source.type === "github") {
+        const fetched = await fetchRepositorySnapshot(pkg.source.repository, {
+            ref: pkg.source.ref,
+        });
+        const selected = pkg.source.path
+            ? resolve(fetched.path, pkg.source.path)
+            : fetched.path;
+        if (selected !== fetched.path &&
+            !selected.startsWith(`${fetched.path}${sep}`))
+            throw new Error(`Package subpath escapes fetched repository: ${pkg.source.path}`);
+        return {
+            path: selected,
+            repository: fetched.repository,
+            commit: fetched.commit,
+        };
+    }
+    if (pkg.source.type === "git") {
+        const fetched = await fetchGitSnapshot(pkg.source.url, {
+            ref: pkg.source.ref,
+        });
+        const selected = pkg.source.path
+            ? resolve(fetched.path, pkg.source.path)
+            : fetched.path;
+        if (selected !== fetched.path &&
+            !selected.startsWith(`${fetched.path}${sep}`))
+            throw new Error(`Package subpath escapes fetched Git repository: ${pkg.source.path}`);
+        return { path: selected, commit: fetched.commit };
+    }
+    if (pkg.source.type === "registry") {
+        const resolved = await resolveRegistryPackage(pkg.source.name, pkg.source.version);
+        return { path: resolved.path, commit: resolved.digest };
+    }
+    if (pkg.source.type === "remote-registry") {
+        const resolved = await fetchRemoteRegistryPackage(pkg.source.registry, pkg.source.name, pkg.source.version);
+        return { path: resolved.path, commit: resolved.digest };
+    }
+    const catalogId = pkg.source.id;
+    const catalog = await loadEffectiveCatalog();
+    const found = catalog.find((item) => item.id === catalogId);
+    if (!found)
+        throw new Error(`Unknown catalog package '${catalogId}'`);
+    const fetched = await fetchRepositorySnapshot(found.repository);
+    return {
+        path: fetched.path,
+        repository: fetched.repository,
+        commit: fetched.commit,
+    };
+}
+export async function buildSyncPlan(manifestPath = "loadout.json") {
+    const manifestSha256 = createHash("sha256")
+        .update(await readFile(resolve(manifestPath)))
+        .digest("hex");
+    const manifest = await expandRegistryDependencies(await readManifest(manifestPath));
+    const disabled = new Set(manifest.packages
+        .filter((pkg) => pkg.enabled === false)
+        .map((pkg) => pkg.id));
+    for (const pkg of manifest.packages.filter((item) => item.enabled !== false)) {
+        const unavailable = (pkg.dependsOn ?? []).filter((id) => disabled.has(id));
+        if (unavailable.length)
+            throw new Error(`Enabled package '${pkg.id}' depends on disabled package(s): ${unavailable.join(", ")}`);
+    }
+    const detected = await detectAgents();
+    const rootFileTarget = manifest.scope === "project" ? dirname(resolve(manifestPath)) : userHome();
+    const packages = [];
+    const mcpPlans = [];
+    const skipped = [];
+    for (const pkg of orderManifestPackages(manifest.packages).filter((item) => item.enabled !== false)) {
+        const requested = pkg.agents ?? manifest.agents;
+        const agents = installedAgents(detected, requested);
+        const source = await resolvePackage(pkg);
+        let plan;
+        try {
+            plan = await buildUniversalPackagePlan(source.path, pkg.id, agents);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("No supported"))
+                plan = {
+                    packageId: pkg.id,
+                    files: [],
+                    targetAgents: agents.map((agent) => agent.id),
+                    warnings: [],
+                };
+            else
+                throw error;
+        }
+        if (pkg.rootFiles?.length)
+            await addRootFileExports(plan, source.path, rootFileTarget, pkg.rootFiles);
+        const manifests = pkg.mcp ? await discoverMcpManifests(source.path) : [];
+        const allServers = manifests.flatMap((manifest) => manifest.servers);
+        const requestedServers = pkg.mcp?.servers ?? allServers.map((server) => server.name);
+        const selectedServers = requestedServers.map((name) => {
+            const matches = allServers.filter((server) => server.name === name);
+            if (matches.length === 0)
+                throw new Error(`MCP server '${name}' was not found in package '${pkg.id}'`);
+            if (matches.length > 1)
+                throw new Error(`MCP server '${name}' is ambiguous in package '${pkg.id}'`);
+            return matches[0];
+        });
+        if (pkg.mcp && selectedServers.length === 0)
+            throw new Error(`Package '${pkg.id}' has MCP configuration enabled but contains no MCP servers`);
+        if (pkg.mcp)
+            mcpPlans.push({
+                packageId: pkg.id,
+                plan: await planMcpConfigBatch(resolve(pkg.mcp.config), selectedServers.map((server) => ({ server }))),
+            });
+        if (plan.files.length === 0 && selectedServers.length === 0) {
+            skipped.push({
+                packageId: pkg.id,
+                reason: "No supported skill, rule, command, agent, or configured MCP component was found.",
+            });
+            continue;
+        }
+        const safetyPlan = {
+            ...plan,
+            files: [
+                ...plan.files,
+                ...manifests.map((manifest) => ({
+                    source: manifest.path,
+                    target: manifest.path,
+                    componentType: "mcp",
+                })),
+            ],
+        };
+        const safety = await analyzeInstallPlanSafety(safetyPlan);
+        if (pkg.mcp) {
+            safety.approvalRequired = true;
+            safety.findings.push({
+                severity: "blocking",
+                category: "mcp",
+                message: "Package changes MCP configuration and requires explicit approval.",
+                paths: [resolve(pkg.mcp.config)],
+                names: selectedServers.map((server) => server.name),
+            });
+        }
+        packages.push({
+            plan,
+            metadata: {
+                repository: source.repository,
+                resolvedCommit: source.commit,
+            },
+            safety,
+        });
+    }
+    const installStateSha256 = createHash("sha256")
+        .update(JSON.stringify(await readInstallState()))
+        .digest("hex");
+    return {
+        manifest: manifestPath,
+        manifestSha256,
+        installStateSha256,
+        resolvedManifest: manifest,
+        packages,
+        mcpPlans,
+        skipped,
+        policyViolations: policyViolations(manifest, packages),
+    };
+}
+export async function applySyncPlan(plan, lockPath = "loadout.lock", options = {}) {
+    if (plan.skipped.length)
+        throw new Error(`Synchronization cannot produce a reproducible lockfile because package(s) were skipped: ${plan.skipped.map((entry) => `${entry.packageId} (${entry.reason})`).join("; ")}`);
+    if (plan.policyViolations.length)
+        throw new Error(`Synchronization violates manifest policy: ${plan.policyViolations.join("; ")}`);
+    const blocked = plan.packages.filter((entry) => entry.safety.approvalRequired);
+    if (blocked.length && !options.approveRisk)
+        throw new Error(`Synchronization requires explicit risk approval for: ${blocked.map((entry) => entry.plan.packageId).join(", ")}`);
+    const conflicts = detectInstallConflicts(plan.packages.map((entry) => entry.plan));
+    const blockingConflicts = conflicts.filter((conflict) => conflict.severity === "blocking");
+    if (blockingConflicts.length)
+        throw new Error(`Synchronization has blocking target conflicts: ${blockingConflicts.map((conflict) => conflict.message).join("; ")}`);
+    const applied = await runMutationTransaction(async () => {
+        const currentManifestSha256 = createHash("sha256")
+            .update(await readFile(resolve(plan.manifest)))
+            .digest("hex");
+        if (plan.manifestSha256 && currentManifestSha256 !== plan.manifestSha256)
+            throw new Error("Manifest changed after synchronization preview; build the plan again.");
+        const currentStateSha256 = createHash("sha256")
+            .update(JSON.stringify(await readInstallState()))
+            .digest("hex");
+        if (plan.installStateSha256 &&
+            currentStateSha256 !== plan.installStateSha256)
+            throw new Error("Installed state changed after synchronization preview; build the plan again.");
+        return {
+            targets: [
+                ...plan.packages.flatMap((entry) => entry.plan.files.map((file) => file.target)),
+                ...plan.mcpPlans.map((entry) => entry.plan.path),
+                installStatePath(),
+                resolve(lockPath),
+            ],
+            value: plan,
+        };
+    }, async (freshPlan, snapshot) => {
+        for (const entry of freshPlan.packages)
+            if (entry.plan.files.length)
+                await applySkillPlan(entry.plan);
+        for (const entry of freshPlan.mcpPlans)
+            await writeMcpConfigPlan(entry.plan);
+        await recordInstallTransaction(freshPlan.packages, freshPlan.mcpPlans, snapshot.id);
+        await writeLockfile(freshPlan.resolvedManifest ?? (await readManifest(freshPlan.manifest)), lockPath);
+    });
+    return { snapshotId: applied.snapshotId, lockfile: lockPath };
+}

package/dist/src/core/terminal.js

@@ -0,0 +1,53 @@
+const MIN_WIDTH = 80;
+const MAX_WIDTH = 200;
+/** Strip terminal control/escape sequences from untrusted human-readable text. */
+export function safeTerminalText(value) {
+    return (value
+        // eslint-disable-next-line no-control-regex
+        .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
+        // eslint-disable-next-line no-control-regex
+        .replace(/\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "")
+        .replace(/[\r\n\t]+/g, " ")
+        .trim());
+}
+export function terminalWidth(value = process.stdout.columns) {
+    if (!Number.isFinite(value))
+        return 120;
+    return Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, Math.floor(value)));
+}
+function fit(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    if (width <= 1)
+        return value.slice(0, width);
+    return `${value.slice(0, width - 1)}…`;
+}
+/** Render a deterministic ANSI-free table bounded to an 80-200 column terminal. */
+export function formatTerminalTable(headers, rows, requestedWidth) {
+    if (!headers.length)
+        return "";
+    if (rows.some((row) => row.length !== headers.length))
+        throw new Error("Terminal table rows must match the header width");
+    const width = terminalWidth(requestedWidth);
+    const separatorWidth = (headers.length - 1) * 3;
+    const available = Math.max(headers.length, width - separatorWidth);
+    const columns = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index].length), Math.min(4, available)));
+    while (columns.reduce((sum, column) => sum + column, 0) > available) {
+        const largest = Math.max(...columns);
+        const index = columns.findIndex((column) => column === largest);
+        if (columns[index] <= 1)
+            break;
+        columns[index]--;
+    }
+    const line = (cells) => cells
+        .map((cell, index) => fit(cell, columns[index]))
+        .join(" | ")
+        .trimEnd();
+    return [
+        line(headers),
+        columns.map((column) => "-".repeat(column)).join("-|-"),
+        ...rows.map(line),
+    ].join("\n");
+}

package/dist/src/core/transaction.js

@@ -0,0 +1,211 @@
+import { lstat, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+import { createSnapshot, readSnapshot, restoreSnapshot } from "./snapshot.js";
+import { acquireFileLock, withFileLock, } from "./file-lock.js";
+export const transactionRoot = () => join(loadoutHome(), "staging");
+const transactionPreparingRoot = () => join(loadoutHome(), "staging-preparing");
+export const mutationLockPath = () => join(loadoutHome(), "mutation.lock");
+const journalPath = (directory) => join(directory, "transaction.json");
+const validId = (id) => /^\d+-[a-f0-9]{12}$/.test(id);
+async function writeJournal(directory, journal) {
+    const path = journalPath(directory);
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(journal, null, 2)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    await rename(temporary, path);
+}
+function parseJournal(value, directory) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Corrupt Loadout transaction journal in ${directory}`);
+    const journal = value;
+    if (journal.version !== 1 ||
+        typeof journal.id !== "string" ||
+        !validId(journal.id) ||
+        typeof journal.snapshotId !== "string" ||
+        !validId(journal.snapshotId) ||
+        !Array.isArray(journal.targets) ||
+        !journal.targets.every((target) => typeof target === "string") ||
+        typeof journal.createdAt !== "string" ||
+        (journal.status !== "prepared" && journal.status !== "committing")) {
+        throw new Error(`Corrupt Loadout transaction journal in ${directory}`);
+    }
+    if (journal.id !== directory.split(/[\\/]/).at(-1))
+        throw new Error(`Corrupt Loadout transaction journal in ${directory}`);
+    return journal;
+}
+async function readJournal(directory) {
+    try {
+        return parseJournal(JSON.parse(await readFile(journalPath(directory), "utf8")), directory);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith("Corrupt Loadout transaction journal"))
+            throw error;
+        throw new Error(`Corrupt Loadout transaction journal in ${directory}`);
+    }
+}
+export async function beginTransaction(snapshot, targets, options = {}) {
+    const mutationLock = options.mutationLock ?? (await acquireMutationLock());
+    const root = transactionRoot();
+    const preparingRoot = transactionPreparingRoot();
+    let preparingDirectory;
+    try {
+        // Callers build a preview snapshot before this boundary. Refresh it while
+        // holding the global mutation lock so a concurrent completed mutation can
+        // never be rolled back by stale pre-lock bytes.
+        const freshSnapshot = await createSnapshot(targets);
+        Object.assign(snapshot, freshSnapshot);
+        await Promise.all([ensureDirectory(root), ensureDirectory(preparingRoot)]);
+        const directory = join(root, snapshot.id);
+        preparingDirectory = join(preparingRoot, `${snapshot.id}-${randomUUID()}`);
+        await mkdir(preparingDirectory, { recursive: false });
+        const handle = {
+            id: snapshot.id,
+            directory,
+            snapshotId: snapshot.id,
+            mutationLock,
+        };
+        await writeJournal(preparingDirectory, {
+            version: 1,
+            id: handle.id,
+            snapshotId: handle.snapshotId,
+            targets: [...new Set(targets)],
+            createdAt: new Date().toISOString(),
+            status: "prepared",
+        });
+        await rename(preparingDirectory, directory);
+        preparingDirectory = undefined;
+        return handle;
+    }
+    catch (error) {
+        if (preparingDirectory)
+            await rm(preparingDirectory, { recursive: true, force: true });
+        await mutationLock.release();
+        throw error;
+    }
+}
+/** Acquire the global mutation boundary and recover abandoned work before use. */
+export async function acquireMutationLock() {
+    const mutationLock = await acquireFileLock(mutationLockPath(), {
+        timeoutMs: 30_000,
+    });
+    try {
+        // No live transaction can be preparing while this lock is held. Any
+        // unpublished directory is crash debris and was never visible to recovery.
+        await rm(transactionPreparingRoot(), { recursive: true, force: true });
+        // Recovery and the next mutation share one acquisition. Otherwise a
+        // process could die between a caller's recovery pass and its state checks.
+        await recoverPendingTransactionsUnlocked();
+        return mutationLock;
+    }
+    catch (error) {
+        await mutationLock.release();
+        throw error;
+    }
+}
+/** Serialize a direct mutation or restore that does not need a new journal. */
+export async function withMutationLock(operation) {
+    const mutationLock = await acquireMutationLock();
+    try {
+        return await operation();
+    }
+    finally {
+        await mutationLock.release();
+    }
+}
+/**
+ * Prepare from current state, snapshot, journal, mutate, and commit under one
+ * global lock. Network/source preparation should happen before this boundary;
+ * every state-dependent precondition belongs in `prepare`.
+ */
+export async function runMutationTransaction(prepare, mutate) {
+    const mutationLock = await acquireMutationLock();
+    let transaction;
+    try {
+        const prepared = await prepare();
+        const snapshot = await createSnapshot(prepared.targets, {
+            persist: false,
+        });
+        transaction = await beginTransaction(snapshot, prepared.targets, {
+            mutationLock,
+        });
+        await markTransactionCommitting(transaction);
+        const result = await mutate(prepared.value, snapshot);
+        await completeTransaction(transaction);
+        return { snapshotId: snapshot.id, result };
+    }
+    catch (error) {
+        if (transaction)
+            await rollbackTransaction(transaction);
+        else
+            await mutationLock.release();
+        throw error;
+    }
+}
+export async function markTransactionCommitting(handle) {
+    const journal = await readJournal(handle.directory);
+    await writeJournal(handle.directory, { ...journal, status: "committing" });
+}
+export async function completeTransaction(handle, options = {}) {
+    try {
+        await rm(handle.directory, { recursive: true, force: true });
+    }
+    finally {
+        if (options.releaseLock !== false)
+            await handle.mutationLock.release();
+    }
+}
+export async function rollbackTransaction(handle) {
+    try {
+        await restoreSnapshot(await readSnapshot(handle.snapshotId));
+    }
+    catch (error) {
+        // Preserve the journal for a later recovery attempt, but never strand the
+        // process-global mutation lock when restoration itself fails.
+        await handle.mutationLock.release();
+        throw error;
+    }
+    await completeTransaction(handle);
+}
+/**
+ * Restore every complete, readable pending transaction. Corrupt journals are
+ * deliberately preserved for inspection and reported instead of guessing at
+ * paths to delete or restore.
+ */
+export async function recoverPendingTransactions() {
+    return withFileLock(mutationLockPath(), recoverPendingTransactionsUnlocked, {
+        timeoutMs: 30_000,
+    });
+}
+async function recoverPendingTransactionsUnlocked() {
+    const root = transactionRoot();
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const recovered = [];
+    for (const entry of entries.sort()) {
+        const directory = join(root, entry);
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error(`Unsafe Loadout transaction staging entry: ${directory}`);
+        const journal = await readJournal(directory);
+        await restoreSnapshot(await readSnapshot(journal.snapshotId));
+        await rm(directory, { recursive: true, force: true });
+        recovered.push(journal.id);
+    }
+    return recovered;
+}

package/dist/src/core/update-watch.js

@@ -0,0 +1,39 @@
+import { buildUpdatePlan } from "./update.js";
+export async function checkForUpdates(check = buildUpdatePlan) {
+    const updates = await check();
+    const pending = updates.filter((item) => item.status === "update-available");
+    return {
+        checkedAt: new Date().toISOString(),
+        updates,
+        message: pending.length
+            ? `${pending.length} update(s) available; review the diff before applying.`
+            : "No tracked updates require action.",
+    };
+}
+/** Start a read-only watcher. It never applies updates or changes agent files. */
+export function startUpdateWatcher(options) {
+    if (!Number.isFinite(options.intervalMs) || options.intervalMs < 1_000)
+        throw new Error("Update watcher interval must be at least 1000ms");
+    let stopped = false;
+    const run = async () => {
+        if (stopped)
+            return;
+        try {
+            options.notify(await checkForUpdates(options.check));
+        }
+        catch (error) {
+            options.notify({
+                checkedAt: new Date().toISOString(),
+                updates: [],
+                message: `Update check failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    };
+    void run();
+    const timer = setInterval(() => void run(), options.intervalMs);
+    timer.unref?.();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}