@kisev/skills-opencode 1.1.1 → 2.0.0

package/dist/installer.js

@@ -1,14 +1,52 @@
 import { readFileSync } from "node:fs";
 import { lstat, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildAgentProfilePlan, listAgentProfiles, validateBuiltAgentProfilePlan, } from "./agent-profiles.js";
-import { applyTransaction, consumeReceipt, deploymentRoot, destination, digest, LifecycleError, lifecycleRoot, readRegular, recoverTransaction, saveReceipt, sha256, stable, withLifecycleLock, } from "./lifecycle.js";
+import { applyTransaction, archiveRoot, consumeReceipt, deploymentRoot, destination, digest, LifecycleError, lifecycleRoot, readRegular, recoverTransaction, saveReceipt, sha256, stable, withLifecycleLock, } from "./lifecycle.js";
+import { CATALOG } from "./catalog.js";
+import { FIXED_AGENT_ROLES } from "./agent-profiles.js";
 const PACKAGE_NAME = "@kisev/skills-opencode";
 const MANIFEST_NAME = ".skills-opencode-manifest.json";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const assetsRoot = resolve(packageRoot, "assets");
+const assetsRoot = resolve(packageRoot, "dist", "assets");
+function retiredAssetPaths() {
+    const inventory = JSON.parse(readFileSync(resolve(assetsRoot, "migration-inventory.json"), "utf8"));
+    return new Set([
+        ...Object.keys(inventory.retired_command_hashes ?? {}),
+        ...Object.keys(inventory.retired_plugin_hashes ?? {}),
+    ]);
+}
+export const SELECTABLE_PLUGINS = [...CATALOG.plugins];
+export const PACKAGE_COMMANDS = [...CATALOG.package_commands];
+export const SKILL_COMMANDS = [...CATALOG.skills];
+export function defaultSelection() {
+    return {
+        commands: [...SKILL_COMMANDS, ...PACKAGE_COMMANDS].sort(),
+        agents: [...FIXED_AGENT_ROLES],
+        plugins: [],
+        core_activation: true,
+    };
+}
+export function normalizeSelection(value = {}) {
+    const allCommands = new Set([...SKILL_COMMANDS, ...PACKAGE_COMMANDS]);
+    const commands = [...new Set(value.commands ?? defaultSelection().commands)].sort();
+    const agents = [...new Set(value.agents ?? FIXED_AGENT_ROLES)];
+    const plugins = [...new Set(value.plugins ?? [])];
+    if (commands.some((name) => !allCommands.has(name)))
+        throw new InstallerError("invalid_selection", "Unknown command selection");
+    if (agents.some((name) => !FIXED_AGENT_ROLES.includes(name)))
+        throw new InstallerError("invalid_selection", "Unknown agent selection");
+    if (plugins.some((name) => !SELECTABLE_PLUGINS.includes(name)))
+        throw new InstallerError("invalid_selection", "Unknown plugin selection");
+    return {
+        commands,
+        agents: agents.sort(),
+        plugins: plugins.sort(),
+        core_activation: Boolean(value.core_activation ?? (commands.some((name) => PACKAGE_COMMANDS.includes(name)) || agents.length)),
+    };
+}
 export class InstallerError extends LifecycleError {
 }
 function packageVersion() {
@@ -17,14 +55,19 @@ function packageVersion() {
         throw new InstallerError("invalid_package", "Package version is unavailable");
     return metadata.version;
 }
-async function assets() {
+async function assets(selection) {
     const result = [];
     for (const category of ["commands", "plugins"]) {
         const directory = resolve(assetsRoot, category);
         for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
             const extension = category === "plugins" ? ".js" : ".md";
+            const name = entry.name.slice(0, -extension.length);
             if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith(extension))
                 throw new InstallerError("asset_error", `Asset is not a regular ${extension} file: ${entry.name}`);
+            if (category === "plugins" && !selection.plugins.includes(name))
+                continue;
+            if (category === "commands" && !selection.commands.includes(name))
+                continue;
             const relativePath = `${category}/${entry.name}`;
             const content = await readRegular(destination(assetsRoot, relativePath));
             if (!content)
@@ -43,23 +86,143 @@ function parseManifest(raw, path) {
         throw new InstallerError("invalid_manifest", `Ownership manifest is not valid JSON: ${path}`);
     }
     const manifest = value;
-    if (manifest.schema_version !== 1 || manifest.package !== PACKAGE_NAME || typeof manifest.version !== "string" || !manifest.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
+    if (manifest.schema_version === 1 &&
+        manifest.package === PACKAGE_NAME &&
+        typeof manifest.version === "string" &&
+        manifest.files &&
+        typeof manifest.files === "object" &&
+        !Array.isArray(manifest.files)) {
+        const files = Object.fromEntries(Object.entries(manifest.files).map(([relativePath, record]) => [
+            relativePath,
+            {
+                sha256: record.sha256,
+                mode: 0o644,
+                kind: relativePath.startsWith("commands/")
+                    ? "command"
+                    : relativePath.startsWith("plugins/")
+                        ? "plugin"
+                        : relativePath.startsWith("agents/")
+                            ? "agent"
+                            : "state",
+            },
+        ]));
+        return {
+            schema_version: 1,
+            package: PACKAGE_NAME,
+            package_version: manifest.version,
+            version: manifest.version,
+            scope: "global",
+            commands: Object.keys(files).filter((path) => path.startsWith("commands/")).map((path) => path.slice(9, -3)).sort(),
+            agents: [...FIXED_AGENT_ROLES].filter((role) => `agents/${role}.md` in files),
+            plugins: Object.keys(files).filter((path) => path.startsWith("plugins/")).map((path) => path.slice(8, -3)).filter((name) => SELECTABLE_PLUGINS.includes(name)),
+            core_activation: true,
+            files,
+        };
+    }
+    if (manifest.schema_version !== 2 || manifest.package !== PACKAGE_NAME || typeof manifest.package_version !== "string" || (manifest.scope !== "global" && manifest.scope !== "project") || !Array.isArray(manifest.commands) || !Array.isArray(manifest.agents) || !Array.isArray(manifest.plugins) || typeof manifest.core_activation !== "boolean" || !manifest.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) {
         throw new InstallerError("invalid_manifest", `Ownership manifest has an unexpected format: ${path}`);
     }
-    for (const [relativePath, record] of Object.entries(manifest.files)) {
+    const files = Object.fromEntries(Object.entries(manifest.files).map(([relativePath, record]) => {
         destination("/", relativePath);
         if (!record || typeof record !== "object" || typeof record.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.sha256)) {
             throw new InstallerError("invalid_manifest", `Ownership manifest has an invalid record: ${relativePath}`);
         }
-    }
-    return manifest;
+        const existing = record;
+        return [relativePath, {
+                sha256: existing.sha256,
+                mode: Number.isInteger(existing.mode) ? existing.mode : 0o644,
+                kind: ["command", "agent", "plugin", "state"].includes(String(existing.kind)) ? existing.kind : relativePath.startsWith("commands/") ? "command" : relativePath.startsWith("plugins/") ? "plugin" : relativePath.startsWith("agents/") ? "agent" : "state",
+            }];
+    }));
+    return { ...manifest, files };
 }
 async function currentManifest(root) {
     const path = destination(root, MANIFEST_NAME);
     const raw = await readRegular(path);
     return raw ? { manifest: parseManifest(raw, path), raw } : {};
 }
-async function validateGenericDeployment(root, action, expectedAssets, plannedOperations, expectedManifest) {
+export async function archiveMutations(candidates, scope, cwd, home, sourceVersion) {
+    if (!candidates.length)
+        return [];
+    const root = archiveRoot(scope, cwd, home);
+    const rootInfo = await lstat(root).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new InstallerError("unsafe_path", "Archive root is inaccessible");
+    });
+    if (rootInfo && (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || (rootInfo.mode & 0o077) !== 0))
+        throw new InstallerError("unsafe_path", "Archive root must be a private directory");
+    const objectsInfo = await lstat(join(root, "objects")).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new InstallerError("unsafe_path", "Archive object store is inaccessible");
+    });
+    if (objectsInfo && (!objectsInfo.isDirectory() || objectsInfo.isSymbolicLink() || (objectsInfo.mode & 0o077) !== 0))
+        throw new InstallerError("unsafe_path", "Archive object store must be private");
+    const indexPath = destination(root, "index.json");
+    const existingRaw = await readRegular(indexPath);
+    if (existingRaw) {
+        const indexInfo = await lstat(indexPath);
+        if ((indexInfo.mode & 0o777) !== 0o600)
+            throw new InstallerError("unsafe_path", "Archive index must be private");
+    }
+    let entries = [];
+    if (existingRaw) {
+        try {
+            const parsed = JSON.parse(existingRaw.toString("utf8"));
+            if (parsed.schema_version !== 1 || !Array.isArray(parsed.entries))
+                throw new Error("invalid archive index");
+            entries = parsed.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+        }
+        catch {
+            throw new InstallerError("invalid_archive", "Archive index is not valid content-addressed state");
+        }
+    }
+    const known = new Set(entries.map((entry) => `${String(entry.original_path)}:${String(entry.digest)}`));
+    const mutations = [];
+    const now = new Date(0).toISOString();
+    for (const candidate of candidates) {
+        const digestValue = sha256(candidate.content);
+        const key = `${candidate.path}:${digestValue}`;
+        if (known.has(key))
+            continue;
+        const objectPath = `objects/${digestValue}`;
+        const object = await readRegular(destination(root, objectPath));
+        if (!object) {
+            mutations.push({
+                root,
+                path: objectPath,
+                operation: "write",
+                content: candidate.content,
+                mode: candidate.record.mode,
+                expected: { absent: true },
+            });
+        }
+        else if (sha256(object) !== digestValue) {
+            throw new InstallerError("archive_collision", `Archive object collision: ${digestValue}`);
+        }
+        entries.push({
+            schema_version: 1,
+            digest: digestValue,
+            original_path: candidate.path,
+            scope,
+            kind: candidate.kind,
+            reason: candidate.reason,
+            package_version: packageVersion(),
+            source_version: sourceVersion,
+            original_hash: candidate.record.sha256,
+            mode: candidate.record.mode,
+            timestamp: now,
+        });
+        known.add(key);
+    }
+    const next = Buffer.from(`${stable({ schema_version: 1, version: packageVersion(), entries: entries.sort((a, b) => String(a.original_path).localeCompare(String(b.original_path)) || String(a.digest).localeCompare(String(b.digest))) })}\n`);
+    if (!existingRaw || !existingRaw.equals(next)) {
+        mutations.push({ root, path: "index.json", operation: "write", content: next, mode: 0o600, expected: existingRaw ? { sha256: sha256(existingRaw) } : { absent: true } });
+    }
+    return mutations;
+}
+async function validateGenericDeployment(root, action, expectedAssets, plannedOperations, expectedManifest, retiredPaths) {
     const owned = await currentManifest(root);
     if ((expectedManifest && (!owned.raw || !owned.raw.equals(expectedManifest))) ||
         (!expectedManifest && owned.raw))
@@ -73,7 +236,10 @@ async function validateGenericDeployment(root, action, expectedAssets, plannedOp
         throw new InstallerError("final_validation_failed", "Generic ownership manifest is not private");
     const expected = new Map(expectedAssets.map((asset) => [asset.relativePath, asset]));
     if (action === "install" &&
-        Object.keys(owned.manifest.files).sort().join(",") !== [...expected.keys()].sort().join(",")) {
+        Object.keys(owned.manifest.files)
+            .filter((path) => !retiredPaths.has(path))
+            .sort()
+            .join(",") !== [...expected.keys()].sort().join(",")) {
         throw new InstallerError("final_validation_failed", "Generic ownership inventory is incomplete");
     }
     for (const [relativePath, record] of Object.entries(owned.manifest.files)) {
@@ -89,28 +255,45 @@ async function validateGenericDeployment(root, action, expectedAssets, plannedOp
         if (!content || (sha256(content) !== record.sha256 && !preservedDrift))
             throw new InstallerError("final_validation_failed", `Generic managed file failed final validation: ${relativePath}`);
         const asset = expected.get(relativePath);
-        if (action === "install" && (!asset || asset.sha256 !== record.sha256))
+        if (action === "install" &&
+            ((!asset && !retiredPaths.has(relativePath)) || (asset && asset.sha256 !== record.sha256)))
             throw new InstallerError("final_validation_failed", `Generic manifest does not match package asset: ${relativePath}`);
-        if (action === "install" && ((await lstat(target)).mode & 0o777) !== asset.mode)
+        if (action === "install" && asset && ((await lstat(target)).mode & 0o777) !== asset.mode)
             throw new InstallerError("final_validation_failed", `Generic managed file has an unexpected mode: ${relativePath}`);
     }
 }
 function asLegacy(manifest) {
     return manifest?.version === "1.0.0" ? manifest : undefined;
 }
-async function build(action, scope, cwd = process.cwd(), home = homedir()) {
+async function build(action, scope, cwd = process.cwd(), home = homedir(), requestedSelection) {
     const root = deploymentRoot(scope, cwd, home);
-    const [owned, bundled] = await Promise.all([currentManifest(root), assets()]);
+    const owned = await currentManifest(root);
+    const selection = normalizeSelection(requestedSelection ??
+        (owned.manifest
+            ? {
+                commands: owned.manifest.commands,
+                agents: owned.manifest.agents,
+                plugins: owned.manifest.plugins,
+                core_activation: owned.manifest.core_activation,
+            }
+            : undefined));
+    const bundled = await assets(selection);
+    const retiredPaths = retiredAssetPaths();
     const legacyRecord = owned.manifest && owned.raw && asLegacy(owned.manifest)
         ? { manifest: asLegacy(owned.manifest), manifestPath: destination(root, MANIFEST_NAME), manifestSha256: sha256(owned.raw) }
         : undefined;
-    const profiles = await buildAgentProfilePlan({ action }, scope, cwd, home, legacyRecord);
+    const profiles = await buildAgentProfilePlan({ action }, scope, cwd, home, legacyRecord, selection.agents);
     const operations = profiles.plan.operations.map((item) => ({ path: item.path, operation: item.operation, reason: item.reason }));
     const mutations = [...profiles.mutations];
+    const archiveCandidates = [];
     const desiredFiles = {};
     if (action === "install") {
         for (const asset of bundled) {
-            desiredFiles[asset.relativePath] = { sha256: asset.sha256 };
+            desiredFiles[asset.relativePath] = {
+                sha256: asset.sha256,
+                mode: asset.mode,
+                kind: asset.relativePath.startsWith("commands/") ? "command" : "plugin",
+            };
             const current = await readRegular(destination(root, asset.relativePath));
             const record = owned.manifest?.files[asset.relativePath];
             if (!current) {
@@ -136,15 +319,30 @@ async function build(action, scope, cwd = process.cwd(), home = homedir()) {
         for (const [relativePath, record] of Object.entries(owned.manifest?.files ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
             if (active.has(relativePath) || profiles.legacyTransferred.includes(relativePath))
                 continue;
+            const current = await readRegular(destination(root, relativePath));
+            if (retiredPaths.has(relativePath)) {
+                if (!current) {
+                    operations.push({ path: relativePath, operation: "missing", sha256: record.sha256 });
+                }
+                else if (sha256(current) !== record.sha256) {
+                    operations.push({ path: relativePath, operation: "conflict", reason: "managed_file_changed", sha256: sha256(current) });
+                }
+                else {
+                    operations.push({ path: relativePath, operation: "archive-pending", reason: "archive lifecycle is pending", sha256: record.sha256 });
+                    archiveCandidates.push({ path: relativePath, record, content: current, reason: "retired managed asset", kind: record.kind });
+                    mutations.push({ path: relativePath, operation: "remove", expected: { sha256: record.sha256 } });
+                }
+                continue;
+            }
             if (relativePath.startsWith("agents/")) {
                 operations.push({ path: relativePath, operation: "conflict", reason: "v1.0.0_agent_ownership_mismatch" });
                 continue;
             }
-            const current = await readRegular(destination(root, relativePath));
             if (!current)
                 operations.push({ path: relativePath, operation: "missing" });
             else if (sha256(current) === record.sha256) {
-                operations.push({ path: relativePath, operation: "remove", sha256: record.sha256 });
+                operations.push({ path: relativePath, operation: "archive-pending", reason: "stale managed asset is archived", sha256: record.sha256 });
+                archiveCandidates.push({ path: relativePath, record, content: current, reason: "stale managed asset", kind: record.kind });
                 mutations.push({ path: relativePath, operation: "remove", expected: { sha256: record.sha256 } });
             }
             else
@@ -154,10 +352,24 @@ async function build(action, scope, cwd = process.cwd(), home = homedir()) {
     else {
         for (const [relativePath, record] of Object.entries(owned.manifest?.files ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
             const current = await readRegular(destination(root, relativePath));
-            if (!current)
+            if (retiredPaths.has(relativePath)) {
+                if (!current) {
+                    operations.push({ path: relativePath, operation: "missing", sha256: record.sha256 });
+                }
+                else if (sha256(current) !== record.sha256) {
+                    operations.push({ path: relativePath, operation: "conflict", reason: "managed_file_changed", sha256: sha256(current) });
+                }
+                else {
+                    operations.push({ path: relativePath, operation: "archive-pending", reason: "archive lifecycle is pending", sha256: record.sha256 });
+                    archiveCandidates.push({ path: relativePath, record, content: current, reason: "retired managed asset", kind: record.kind });
+                    mutations.push({ path: relativePath, operation: "remove", expected: { sha256: record.sha256 } });
+                }
+            }
+            else if (!current)
                 operations.push({ path: relativePath, operation: "missing" });
             else if (sha256(current) === record.sha256) {
-                operations.push({ path: relativePath, operation: "remove", sha256: record.sha256 });
+                operations.push({ path: relativePath, operation: "archive-pending", reason: "stale managed asset is archived", sha256: record.sha256 });
+                archiveCandidates.push({ path: relativePath, record, content: current, reason: "stale managed asset", kind: record.kind });
                 mutations.push({ path: relativePath, operation: "remove", expected: { sha256: record.sha256 } });
             }
             else {
@@ -166,8 +378,20 @@ async function build(action, scope, cwd = process.cwd(), home = homedir()) {
             }
         }
     }
+    mutations.push(...await archiveMutations(archiveCandidates, scope, cwd, home, owned.manifest?.package_version ?? "1.0.0"));
     const nextManifest = action === "install" || Object.keys(desiredFiles).length
-        ? { schema_version: 1, package: PACKAGE_NAME, version: packageVersion(), files: desiredFiles }
+        ? {
+            schema_version: 2,
+            package: PACKAGE_NAME,
+            package_version: packageVersion(),
+            version: packageVersion(),
+            scope,
+            commands: selection.commands,
+            agents: selection.agents,
+            plugins: selection.plugins,
+            core_activation: selection.core_activation,
+            files: desiredFiles,
+        }
         : undefined;
     const manifestContent = nextManifest ? Buffer.from(`${stable(nextManifest)}\n`) : undefined;
     if (manifestContent && (!owned.raw || !owned.raw.equals(manifestContent))) {
@@ -179,7 +403,7 @@ async function build(action, scope, cwd = process.cwd(), home = homedir()) {
         mutations.push({ path: MANIFEST_NAME, operation: "remove", expected: { sha256: sha256(owned.raw) } });
     }
     const sorted = operations.sort((left, right) => left.path.localeCompare(right.path) || left.operation.localeCompare(right.operation));
-    const base = { schema_version: 1, action, scope, root, package_version: packageVersion(), operations: sorted, requires_restart: (action === "install" && owned.manifest?.version !== packageVersion()) || profiles.plan.requires_restart || mutations.some((item) => item.path.startsWith("agents/") || item.path.startsWith("commands/") || item.path.startsWith("plugins/")) };
+    const base = { schema_version: 2, action, scope, root, package_version: packageVersion(), selection, operations: sorted, requires_restart: (action === "install" && owned.manifest?.package_version !== packageVersion()) || profiles.plan.requires_restart || mutations.some((item) => item.path.startsWith("agents/") || item.path.startsWith("commands/") || item.path.startsWith("plugins/")) };
     return {
         plan: { ...base, digest: digest(base) },
         mutations,
@@ -187,14 +411,14 @@ async function build(action, scope, cwd = process.cwd(), home = homedir()) {
         profiles,
     };
 }
-export async function preview(action, scope, cwd = process.cwd(), home = homedir()) {
+export async function preview(action, scope, cwd = process.cwd(), home = homedir(), selection) {
     const stateRoot = lifecycleRoot(scope, cwd, home);
     const root = deploymentRoot(scope, cwd, home);
     try {
         return await withLifecycleLock(stateRoot, async () => {
             if (await recoverTransaction(root, stateRoot))
                 throw new InstallerError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
-            const built = await build(action, scope, cwd, home);
+            const built = await build(action, scope, cwd, home, selection);
             const receipt = await saveReceipt(stateRoot, `installer:${action}`, scope, root, { digest: built.plan.digest });
             return { ...built.plan, digest: receipt.digest, receipt_expires_at: receipt.expires_at };
         });
@@ -207,7 +431,7 @@ export async function preview(action, scope, cwd = process.cwd(), home = homedir
         throw error;
     }
 }
-export async function apply(action, scope, confirmationDigest, cwd = process.cwd(), home = homedir(), options = {}) {
+export async function apply(action, scope, confirmationDigest, cwd = process.cwd(), home = homedir(), options = {}, selection) {
     const stateRoot = lifecycleRoot(scope, cwd, home);
     const root = deploymentRoot(scope, cwd, home);
     try {
@@ -215,7 +439,7 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
             if (await recoverTransaction(root, stateRoot))
                 throw new InstallerError("recovered_transaction", "Recovered an interrupted transaction; request a fresh plan");
             const receipt = (await consumeReceipt(stateRoot, { digest: confirmationDigest, kind: `installer:${action}`, scope, root }));
-            const built = await build(action, scope, cwd, home);
+            const built = await build(action, scope, cwd, home, selection);
             if (built.plan.digest !== receipt.digest)
                 throw new InstallerError("stale_plan", "Installer plan changed after preview");
             if (built.plan.operations.some((item) => item.operation === "conflict" && (item.reason === "unmanaged_file" || item.reason === "v1.0.0_agent_ownership_mismatch" || item.reason?.includes("collision")))) {
@@ -228,11 +452,11 @@ export async function apply(action, scope, confirmationDigest, cwd = process.cwd
                 validateFinal: async () => {
                     await options.validateFinal?.();
                     await validateBuiltAgentProfilePlan(built.profiles);
-                    await validateGenericDeployment(root, action, await assets(), built.plan.operations, built.expectedManifest);
+                    await validateGenericDeployment(root, action, await assets(built.plan.selection), built.plan.operations, built.expectedManifest, retiredAssetPaths());
                     if (action !== "install")
                         return;
                     const inventory = await listAgentProfiles(scope, cwd, home);
-                    if (inventory.collisions.length || inventory.drift.length || inventory.profiles.filter((item) => item.ownership !== "user-owned").some((item) => item.state !== "current")) {
+                    if (built.plan.selection.agents.length > 0 && (inventory.collisions.length || inventory.drift.length || inventory.profiles.filter((item) => item.ownership !== "user-owned").some((item) => item.state !== "current"))) {
                         throw new InstallerError("final_validation_failed", "Final installed agent inventory is invalid");
                     }
                 },

package/dist/lifecycle.d.ts

@@ -10,12 +10,14 @@ export type FileExpectation = {
 };
 export type FileMutation = {
     path: string;
+    root?: string;
     operation: "write";
     content: Buffer;
     mode: number;
     expected: FileExpectation;
 } | {
     path: string;
+    root?: string;
     operation: "remove";
     expected: FileExpectation;
 };
@@ -32,6 +34,7 @@ export declare function readRegular(path: string): Promise<Buffer | undefined>;
 export declare function writeAtomic(path: string, content: Buffer, mode: number): Promise<void>;
 export declare function deploymentRoot(scope: Scope, cwd?: string, home?: string): string;
 export declare function lifecycleRoot(scope: Scope, cwd?: string, home?: string): string;
+export declare function archiveRoot(scope: Scope, cwd?: string, home?: string): string;
 export declare function withLifecycleLock<T>(stateRoot: string, callback: () => Promise<T>): Promise<T>;
 export declare function saveReceipt(stateRoot: string, kind: string, scope: Scope, root: string, payload: unknown, now?: number): Promise<{
     digest: string;

package/dist/lifecycle.js

@@ -151,6 +151,12 @@ export function lifecycleRoot(scope, cwd = process.cwd(), home = homedir()) {
     const suffix = scope === "global" ? "global" : join("project", sha256(resolve(cwd)));
     return join(base, "opencode", "skills-opencode", suffix);
 }
+export function archiveRoot(scope, cwd = process.cwd(), home = homedir()) {
+    const base = process.env.XDG_DATA_HOME && home === homedir()
+        ? resolve(process.env.XDG_DATA_HOME)
+        : resolve(home, ".local", "share");
+    return join(base, "opencode", "skills-opencode", "archive", scope);
+}
 async function processAlive(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0)
         return false;
@@ -331,16 +337,25 @@ export async function consumeReceipt(stateRoot, expected, now = Date.now()) {
 function journalPath(stateRoot) {
     return join(stateRoot, "transaction-journal.json");
 }
+function mutationRoot(root, mutation) {
+    return resolve(mutation.root ?? root);
+}
 async function snapshot(root, mutation) {
-    const target = destination(root, mutation.path);
+    const targetRoot = mutationRoot(root, mutation);
+    const target = destination(targetRoot, mutation.path);
     const content = await readRegular(target);
     if (!content)
-        return { path: mutation.path, content: null, mode: null };
+        return { path: mutation.path, root: targetRoot, content: null, mode: null };
     const metadata = await stat(target);
-    return { path: mutation.path, content: content.toString("base64"), mode: metadata.mode & 0o777 };
+    return {
+        path: mutation.path,
+        root: targetRoot,
+        content: content.toString("base64"),
+        mode: metadata.mode & 0o777,
+    };
 }
 async function validateExpectation(root, mutation) {
-    const current = await readRegular(destination(root, mutation.path));
+    const current = await readRegular(destination(mutationRoot(root, mutation), mutation.path));
     if (mutation.expected.absent) {
         if (current)
             throw new LifecycleError("stale_plan", `Expected an absent target: ${mutation.path}`);
@@ -358,7 +373,7 @@ async function restore(root, journal) {
     for (let index = journal.snapshots.length - 1; index >= 0; index -= 1) {
         const item = journal.snapshots[index];
         const operation = journal.operations[index];
-        const target = destination(root, item.path);
+        const target = destination(item.root, item.path);
         const current = await readRegular(target);
         const currentHash = current ? sha256(current) : undefined;
         const currentMode = current ? (await lstat(target)).mode & 0o777 : undefined;
@@ -436,8 +451,11 @@ function parseJournal(raw, expectedRoot) {
                 journal.applying >= journal.operations.length))) {
         throw new LifecycleError("invalid_journal", "Transaction journal has an unsupported schema");
     }
-    for (const item of journal.snapshots)
+    for (const item of journal.snapshots) {
         assertSafeRelative(item.path);
+        if (item.root !== undefined && !isAbsolute(item.root))
+            throw new LifecycleError("invalid_journal", "Transaction snapshot root must be absolute");
+    }
     for (const item of journal.snapshots) {
         if ((item.content !== null &&
             (typeof item.content !== "string" ||
@@ -449,6 +467,8 @@ function parseJournal(raw, expectedRoot) {
     }
     for (const item of journal.operations) {
         assertSafeRelative(item.path);
+        if (item.root !== undefined && !isAbsolute(item.root))
+            throw new LifecycleError("invalid_journal", "Transaction operation root must be absolute");
         if (item.operation !== "write" && item.operation !== "remove")
             throw new LifecycleError("invalid_journal", "Transaction journal contains an invalid operation");
         if (item.operation === "write" &&
@@ -462,14 +482,18 @@ function parseJournal(raw, expectedRoot) {
     }
     if (!journal.created_directories.every((item) => item &&
         typeof item.path === "string" &&
-        inside(resolve(expectedRoot), resolve(item.path)) &&
+        (inside(resolve(expectedRoot), resolve(item.path)) ||
+            (journal.operations ?? []).some((operation) => operation.root && inside(resolve(operation.root), resolve(item.path)))) &&
         Number.isSafeInteger(item.device) &&
         item.device >= 0 &&
         Number.isSafeInteger(item.inode) &&
         item.inode > 0)) {
         throw new LifecycleError("invalid_journal", "Transaction journal contains an unsafe created directory");
     }
-    return journal;
+    return {
+        ...journal,
+        snapshots: journal.snapshots.map((item) => ({ ...item, root: item.root ?? expectedRoot })),
+    };
 }
 export async function recoverTransaction(root, stateRoot) {
     const raw = await readRegular(journalPath(stateRoot));
@@ -481,12 +505,13 @@ export async function recoverTransaction(root, stateRoot) {
     return true;
 }
 async function ensureTransactionDirectories(root, mutation, stateRoot, journal) {
-    await ensureDirectory(dirname(resolve(root)), 0o700);
-    const relativeParent = relative(resolve(root), dirname(destination(root, mutation.path)));
+    const targetRoot = mutationRoot(root, mutation);
+    await ensureDirectory(dirname(targetRoot), 0o700);
+    const relativeParent = relative(targetRoot, dirname(destination(targetRoot, mutation.path)));
     const parts = relativeParent.split(sep).filter(Boolean);
     const directories = [
-        resolve(root),
-        ...parts.map((_, index) => resolve(root, ...parts.slice(0, index + 1))),
+        targetRoot,
+        ...parts.map((_, index) => resolve(targetRoot, ...parts.slice(0, index + 1))),
     ];
     for (const directory of directories) {
         const existing = await lstatSafe(directory);
@@ -521,9 +546,10 @@ export async function applyTransaction(root, stateRoot, mutations, options = {})
     const unique = new Set();
     for (const mutation of mutations) {
         assertSafeRelative(mutation.path);
-        if (unique.has(mutation.path))
+        const key = `${mutationRoot(root, mutation)}:${mutation.path}`;
+        if (unique.has(key))
             throw new LifecycleError("invalid_plan", `Duplicate transaction target: ${mutation.path}`);
-        unique.add(mutation.path);
+        unique.add(key);
         await validateExpectation(root, mutation);
     }
     const snapshots = await Promise.all(mutations.map((mutation) => snapshot(root, mutation)));
@@ -533,12 +559,18 @@ export async function applyTransaction(root, stateRoot, mutations, options = {})
         operations: mutations.map((mutation) => mutation.operation === "write"
             ? {
                 path: mutation.path,
+                ...(mutation.root ? { root: resolve(mutation.root) } : {}),
                 operation: mutation.operation,
                 content: mutation.content.toString("base64"),
                 mode: mutation.mode,
                 expected: mutation.expected,
             }
-            : { path: mutation.path, operation: mutation.operation, expected: mutation.expected }),
+            : {
+                path: mutation.path,
+                ...(mutation.root ? { root: resolve(mutation.root) } : {}),
+                operation: mutation.operation,
+                expected: mutation.expected,
+            }),
         snapshots,
         created_directories: [],
         published: 0,
@@ -553,7 +585,7 @@ export async function applyTransaction(root, stateRoot, mutations, options = {})
             if (mutation.operation === "write")
                 await ensureTransactionDirectories(root, mutation, stateRoot, journal);
             await validateExpectation(root, mutation);
-            const target = destination(root, mutation.path);
+            const target = destination(mutationRoot(root, mutation), mutation.path);
             if (mutation.operation === "write")
                 await writeAtomic(target, mutation.content, mutation.mode);
             else
@@ -568,7 +600,7 @@ export async function applyTransaction(root, stateRoot, mutations, options = {})
                 throw new LifecycleError("test_failure", "Injected transaction failure");
         }
         for (const mutation of mutations) {
-            const target = destination(root, mutation.path);
+            const target = destination(mutationRoot(root, mutation), mutation.path);
             const current = await readRegular(target);
             if ((mutation.operation === "remove" && current) ||
                 (mutation.operation === "write" &&

package/dist/plugins/rtk.js

@@ -8,6 +8,8 @@ const FILTERS = [
 function filter(command) {
     if (/[|;$&\n()`]/.test(command))
         return undefined;
+    if (/\b(--json|--format(?:=|\s)|diagnos|security|deploy|migrat|delete|remove)\b/i.test(command))
+        return undefined;
     const values = command.trim().split(/\s+/);
     return FILTERS.find((item) => item.prefix.every((part, index) => values[index] === part))?.filter;
 }
@@ -40,7 +42,8 @@ export async function rtk(options = {}) {
                 const selected = typeof input.args?.command === "string" ? filter(input.args.command) : undefined;
                 const compressed = selected ? await run(selected, output.output) : undefined;
                 const result = compressed && compressed.length < output.output.length ? compressed : truncate(output.output);
-                output.output = `${result}\n[rtk: compressed ${output.output.length} chars using ${compressed ? `rtk/${selected}` : "head+tail"}]`;
+                const originalSize = output.output.length;
+                output.output = `${result}\n[rtk: compressed method=${compressed ? `rtk/${selected}` : "head+tail"}; sizes=${originalSize}->${result.length}; evidence_complete=false; loss=possible]`;
             }
             catch { /* RTK is fail-open: preserve original tool output on plugin failure. */ }
         } };