@nggaigc/cli 0.1.10 → 0.1.12

package/dist/independent-skill.js

@@ -0,0 +1,690 @@
+import { createHash, createPublicKey, randomUUID, verify } from "node:crypto";
+import { open, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+const ID = /^skill\.[a-z0-9][a-z0-9.-]{0,79}$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const MAX_PACKAGE_BYTES = 4 * 1024 * 1024;
+const MAX_FILES = 32;
+export class IndependentSkillError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "IndependentSkillError";
+    }
+}
+function fail(code) {
+    throw new IndependentSkillError(code);
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonical(child)}`)
+            .join(",")}}`;
+    return JSON.stringify(value);
+}
+function compareVersion(left, right) {
+    if (!VERSION.test(left) || !VERSION.test(right))
+        fail("PACKAGE_INCOMPATIBLE");
+    const a = left.split(".").map(Number);
+    const b = right.split(".").map(Number);
+    for (let index = 0; index < 3; index++) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return 0;
+}
+function compatible(version, range) {
+    return (compareVersion(version, range.minimum) >= 0 &&
+        compareVersion(version, range.maximumExclusive) < 0);
+}
+function resolve(index, id, version, rootVersion, platformVersion) {
+    if (index.schemaVersion !== "nggaigc-independent-skill-index/v1" ||
+        !ID.test(id) ||
+        !index.releaseId ||
+        !Array.isArray(index.entries))
+        fail("CATALOG_INVALID");
+    const state = new Map();
+    const ordered = [];
+    const visit = (skillId, requiredVersion) => {
+        if (!ID.test(skillId))
+            fail("CATALOG_INVALID");
+        const matches = index.entries.filter((entry) => entry.id === skillId &&
+            (requiredVersion === undefined || entry.version === requiredVersion));
+        if (matches.length !== 1)
+            fail("DEPENDENCY_UNAVAILABLE");
+        const entry = matches[0];
+        const key = `${entry.id}@${entry.version}`;
+        if (state.get(key) === "visiting")
+            fail("DEPENDENCY_CYCLE");
+        if (state.get(key) === "done")
+            return;
+        if (entry.state !== "active" ||
+            entry.manifest.lifecycle.status !== "published" ||
+            entry.manifest.id !== entry.id ||
+            entry.manifest.version !== entry.version ||
+            !DIGEST.test(entry.manifestSha256) ||
+            sha256(canonical(entry.sourceManifest ?? entry.manifest)) !==
+                entry.manifestSha256)
+            fail("CATALOG_INVALID");
+        const metadata = entry.manifest.package;
+        if (!DIGEST.test(metadata.sha256) ||
+            !Number.isSafeInteger(metadata.sizeBytes) ||
+            metadata.sizeBytes < 1 ||
+            metadata.sizeBytes > MAX_PACKAGE_BYTES ||
+            !compatible(rootVersion, metadata.compatibility.rootSkill) ||
+            !compatible(platformVersion, metadata.compatibility.platform))
+            fail("PACKAGE_INCOMPATIBLE");
+        const dependencies = entry.manifest.requires;
+        if (!Array.isArray(dependencies) ||
+            dependencies.length > 16 ||
+            !dependencies.every((item) => record(item) &&
+                typeof item.id === "string" &&
+                typeof item.version === "string" &&
+                VERSION.test(item.version)) ||
+            ordered.length + state.size > 32)
+            fail("DEPENDENCY_INVALID");
+        state.set(key, "visiting");
+        for (const dependency of dependencies)
+            visit(dependency.id, dependency.version);
+        state.set(key, "done");
+        ordered.push(entry);
+    };
+    if (!VERSION.test(version))
+        fail("CATALOG_INVALID");
+    visit(id, version);
+    return ordered;
+}
+function exactKeys(value, expected) {
+    return (JSON.stringify(Object.keys(value).sort()) ===
+        JSON.stringify([...expected].sort()));
+}
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Projects the one active public catalog; this is not a second release index. */
+export function projectActiveSkillCatalog(snapshot) {
+    if (!record(snapshot) ||
+        typeof snapshot.releaseId !== "string" ||
+        !Array.isArray(snapshot.entries))
+        fail("CATALOG_INVALID");
+    const publicEntries = [];
+    for (const candidate of snapshot.entries) {
+        if (!record(candidate) ||
+            typeof candidate.kind !== "string" ||
+            typeof candidate.id !== "string" ||
+            typeof candidate.version !== "string" ||
+            typeof candidate.manifestSha256 !== "string" ||
+            !record(candidate.manifest) ||
+            candidate.manifest.kind !== candidate.kind ||
+            candidate.manifest.id !== candidate.id ||
+            candidate.manifest.version !== candidate.version ||
+            sha256(canonical(candidate.manifest)) !== candidate.manifestSha256)
+            fail("CATALOG_INVALID");
+        publicEntries.push(candidate);
+    }
+    const entries = [];
+    for (const item of publicEntries) {
+        if (item.kind !== "skill")
+            continue;
+        const manifest = item.manifest;
+        if (manifest.role === "root_skill")
+            continue;
+        if (!record(manifest.lifecycle) ||
+            !record(manifest.package) ||
+            !Array.isArray(manifest.dependencies))
+            fail("CATALOG_INVALID");
+        const pkg = manifest.package;
+        if (pkg.version !== item.version ||
+            typeof pkg.artifactPath !== "string" ||
+            !/^packages\/skills\/[a-z0-9.-]+\.zip$/.test(pkg.artifactPath) ||
+            !record(pkg.signature) ||
+            !record(pkg.compatibility) ||
+            !record(pkg.compatibility.rootSkill) ||
+            !record(pkg.compatibility.platform))
+            fail("CATALOG_INVALID");
+        const requires = [];
+        for (const dependency of manifest.dependencies) {
+            if (!record(dependency) ||
+                typeof dependency.kind !== "string" ||
+                typeof dependency.id !== "string" ||
+                typeof dependency.version !== "string" ||
+                dependency.required !== true)
+                fail("DEPENDENCY_INVALID");
+            const matches = publicEntries.filter((candidate) => candidate.kind === dependency.kind &&
+                candidate.id === dependency.id &&
+                candidate.version === dependency.version &&
+                record(candidate.manifest) &&
+                record(candidate.manifest.lifecycle) &&
+                candidate.manifest.lifecycle.status === "published");
+            if (matches.length !== 1)
+                fail("DEPENDENCY_UNAVAILABLE");
+            if (dependency.kind === "skill")
+                requires.push({ id: dependency.id, version: dependency.version });
+            else if (dependency.kind !== "capability")
+                fail("DEPENDENCY_INVALID");
+        }
+        entries.push({
+            id: item.id,
+            version: item.version,
+            manifestSha256: item.manifestSha256,
+            state: "active",
+            sourceManifest: manifest,
+            manifest: {
+                id: item.id,
+                version: item.version,
+                lifecycle: { status: manifest.lifecycle.status },
+                requires,
+                package: {
+                    sha256: pkg.sha256,
+                    sizeBytes: pkg.sizeBytes,
+                    signature: pkg.signature,
+                    compatibility: pkg.compatibility,
+                },
+            },
+        });
+    }
+    return {
+        schemaVersion: "nggaigc-independent-skill-index/v1",
+        releaseId: snapshot.releaseId,
+        entries,
+    };
+}
+function storedZipEntries(input) {
+    const bytes = Buffer.from(input);
+    const end = bytes.length - 22;
+    if (end < 0 ||
+        bytes.readUInt32LE(end) !== 0x06054b50 ||
+        bytes.readUInt16LE(end + 4) !== 0 ||
+        bytes.readUInt16LE(end + 6) !== 0 ||
+        bytes.readUInt16LE(end + 20) !== 0)
+        fail("PACKAGE_VERIFICATION_FAILED");
+    const count = bytes.readUInt16LE(end + 10);
+    const centralSize = bytes.readUInt32LE(end + 12);
+    const centralOffset = bytes.readUInt32LE(end + 16);
+    if (count < 2 || count > MAX_FILES + 1 || centralOffset + centralSize !== end)
+        fail("PACKAGE_VERIFICATION_FAILED");
+    const result = new Map();
+    let cursor = centralOffset;
+    let total = 0;
+    for (let index = 0; index < count; index++) {
+        if (cursor + 46 > end || bytes.readUInt32LE(cursor) !== 0x02014b50)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const flags = bytes.readUInt16LE(cursor + 8);
+        const method = bytes.readUInt16LE(cursor + 10);
+        const checksum = bytes.readUInt32LE(cursor + 16);
+        const compressed = bytes.readUInt32LE(cursor + 20);
+        const uncompressed = bytes.readUInt32LE(cursor + 24);
+        const nameLength = bytes.readUInt16LE(cursor + 28);
+        const extraLength = bytes.readUInt16LE(cursor + 30);
+        const commentLength = bytes.readUInt16LE(cursor + 32);
+        const disk = bytes.readUInt16LE(cursor + 34);
+        const externalAttributes = bytes.readUInt32LE(cursor + 38);
+        const localOffset = bytes.readUInt32LE(cursor + 42);
+        const next = cursor + 46 + nameLength + extraLength + commentLength;
+        if (next > end ||
+            (flags !== 0 && flags !== 0x0800) ||
+            method !== 0 ||
+            compressed !== uncompressed ||
+            uncompressed > MAX_PACKAGE_BYTES ||
+            disk !== 0 ||
+            localOffset + 30 > centralOffset)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const unixMode = externalAttributes >>> 16;
+        if (unixMode !== 0 && (unixMode & 0xf000) !== 0x8000)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const nameBytes = bytes.subarray(cursor + 46, cursor + 46 + nameLength);
+        let name;
+        try {
+            name = new TextDecoder("utf-8", { fatal: true }).decode(nameBytes);
+        }
+        catch {
+            fail("PACKAGE_VERIFICATION_FAILED");
+        }
+        if (!name ||
+            result.has(name) ||
+            bytes.readUInt32LE(localOffset) !== 0x04034b50 ||
+            bytes.readUInt16LE(localOffset + 6) !== flags ||
+            bytes.readUInt16LE(localOffset + 8) !== method)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const localNameLength = bytes.readUInt16LE(localOffset + 26);
+        const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+        const localName = bytes.subarray(localOffset + 30, localOffset + 30 + localNameLength);
+        const start = localOffset + 30 + localNameLength + localExtraLength;
+        if (!localName.equals(nameBytes) ||
+            start + compressed > centralOffset ||
+            bytes.readUInt32LE(localOffset + 14) !== checksum)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        total += uncompressed;
+        if (total > MAX_PACKAGE_BYTES)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const content = bytes.subarray(start, start + compressed);
+        if (crc32(content) !== checksum)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        result.set(name, content);
+        cursor = next;
+    }
+    if (cursor !== end || result.size !== count)
+        fail("PACKAGE_VERIFICATION_FAILED");
+    return result;
+}
+function decodePackage(bytes, entry, trust) {
+    const metadata = entry.manifest.package;
+    if (bytes.length !== metadata.sizeBytes ||
+        sha256(bytes) !== metadata.sha256 ||
+        metadata.signature.algorithm !== "ed25519" ||
+        metadata.signature.keyId !== trust.keyId ||
+        !DIGEST.test(trust.spkiSha256))
+        fail("PACKAGE_VERIFICATION_FAILED");
+    try {
+        const key = createPublicKey(trust.publicKeyPem);
+        const fingerprint = sha256(key.export({ type: "spki", format: "der" }));
+        if (fingerprint !== trust.spkiSha256 ||
+            !verify(null, bytes, key, Buffer.from(metadata.signature.value, "base64")))
+            fail("PACKAGE_VERIFICATION_FAILED");
+    }
+    catch {
+        fail("PACKAGE_VERIFICATION_FAILED");
+    }
+    const archive = storedZipEntries(bytes);
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(archive.get("skill-package.v1.json")));
+    }
+    catch {
+        fail("PACKAGE_VERIFICATION_FAILED");
+    }
+    if (!record(payload) ||
+        payload.schemaVersion !== "ngg-skill-package/v1" ||
+        payload.artifactId !== entry.id ||
+        payload.packageVersion !== entry.version ||
+        canonical(payload.compatibility) !== canonical(metadata.compatibility) ||
+        !Array.isArray(payload.files) ||
+        payload.files.length < 1 ||
+        payload.files.length > MAX_FILES ||
+        !exactKeys(payload, [
+            "schemaVersion",
+            "artifactId",
+            "packageVersion",
+            "compatibility",
+            "files",
+        ]))
+        fail("PACKAGE_VERIFICATION_FAILED");
+    const seen = new Set();
+    let total = 0;
+    for (const file of payload.files) {
+        if (!record(file) ||
+            !exactKeys(file, ["path", "sha256", "sizeBytes", "executable"]))
+            fail("PACKAGE_VERIFICATION_FAILED");
+        if (typeof file.path !== "string" ||
+            file.path !== file.path.normalize("NFC") ||
+            file.path.length > 160 ||
+            file.path.includes("\\") ||
+            file.path.includes(":") ||
+            file.path.startsWith("/") ||
+            file.path
+                .split("/")
+                .some((part) => !part || part === "." || part === ".." || /[. ]$/.test(part)) ||
+            !(file.path === "SKILL.md" ||
+                /^references\/[A-Za-z0-9._/-]+\.(md|json)$/.test(file.path)))
+            fail("PACKAGE_VERIFICATION_FAILED");
+        const folded = file.path.toLowerCase();
+        if (seen.has(folded) ||
+            !DIGEST.test(file.sha256) ||
+            file.executable !== false ||
+            !Number.isSafeInteger(file.sizeBytes))
+            fail("PACKAGE_VERIFICATION_FAILED");
+        seen.add(folded);
+        const content = archive.get(file.path);
+        if (!content)
+            fail("PACKAGE_VERIFICATION_FAILED");
+        total += content.length;
+        if (total > MAX_PACKAGE_BYTES ||
+            content.length !== file.sizeBytes ||
+            sha256(content) !== file.sha256)
+            fail("PACKAGE_VERIFICATION_FAILED");
+    }
+    if (!seen.has("skill.md") || archive.size !== payload.files.length + 1)
+        fail("PACKAGE_VERIFICATION_FAILED");
+    return payload.files.map((file) => ({
+        path: file.path,
+        sha256: file.sha256,
+        contentBase64: archive.get(file.path).toString("base64"),
+    }));
+}
+/** Read-only release gate: use the installer's exact archive and file-list verifier. */
+export function verifyIndependentSkillPackage(bytes, entry, trust) {
+    return decodePackage(bytes, entry, trust).map(({ path, sha256 }) => ({
+        path,
+        sha256,
+    }));
+}
+async function existingReceipt(target, entry, trust) {
+    let receipt;
+    try {
+        const facts = await lstat(target);
+        if (!facts.isDirectory() || facts.isSymbolicLink())
+            fail("INSTALL_CONFLICT");
+        const value = JSON.parse(await readFile(path.join(target, ".nggaigc-package.json"), "utf8"));
+        if (!record(value) ||
+            typeof value.id !== "string" ||
+            typeof value.version !== "string" ||
+            typeof value.sha256 !== "string" ||
+            typeof value.manifestSha256 !== "string" ||
+            !record(value.files))
+            return false;
+        receipt = value;
+    }
+    catch (error) {
+        if (error instanceof IndependentSkillError)
+            throw error;
+        return false;
+    }
+    if (receipt.id !== entry.id ||
+        receipt.version !== entry.version ||
+        receipt.sha256 !== entry.manifest.package.sha256 ||
+        receipt.manifestSha256 !== entry.manifestSha256 ||
+        !receipt.files ||
+        typeof receipt.files !== "object")
+        return false;
+    try {
+        const packageBytes = await readFile(path.join(target, ".nggaigc-package.bin"));
+        const signedFiles = decodePackage(packageBytes, entry, trust);
+        if (JSON.stringify(Object.fromEntries(signedFiles.map((file) => [file.path, file.sha256]))) !== JSON.stringify(receipt.files))
+            return false;
+        const names = [];
+        const walk = async (directory, prefix = "") => {
+            for (const child of await readdir(directory, { withFileTypes: true })) {
+                const name = prefix ? `${prefix}/${child.name}` : child.name;
+                if (child.isSymbolicLink())
+                    throw new Error();
+                if (child.isDirectory())
+                    await walk(path.join(directory, child.name), name);
+                else if (child.isFile())
+                    names.push(name);
+                else
+                    throw new Error();
+            }
+        };
+        await walk(target);
+        if (JSON.stringify(names.sort()) !==
+            JSON.stringify([
+                ...Object.keys(receipt.files),
+                ".nggaigc-package.json",
+                ".nggaigc-package.bin",
+            ].sort()))
+            return false;
+        for (const [name, digest] of Object.entries(receipt.files)) {
+            if (!(name === "SKILL.md" ||
+                /^references\/[A-Za-z0-9._/-]+\.(md|json)$/.test(name)) ||
+                name.split("/").some((part) => part === "." || part === ".."))
+                return false;
+            const file = path.join(target, ...name.split("/"));
+            const facts = await lstat(file);
+            if (!facts.isFile() ||
+                facts.isSymbolicLink() ||
+                sha256(await readFile(file)) !== digest)
+                return false;
+        }
+        return Object.hasOwn(receipt.files, "SKILL.md");
+    }
+    catch {
+        return false;
+    }
+}
+async function download(entry, releaseId, origin, fetcher) {
+    const base = new URL(origin);
+    if (base.protocol !== "https:" ||
+        base.origin !== "https://api.nggaigc.com" ||
+        base.pathname !== "/")
+        fail("PACKAGE_SOURCE_REJECTED");
+    const url = new URL(`/v1/skill-packages/${encodeURIComponent(entry.id)}/${encodeURIComponent(entry.version)}`, base);
+    url.searchParams.set("releaseId", releaseId);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: "GET",
+            redirect: "error",
+            credentials: "omit",
+            cache: "no-store",
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch {
+        fail("PACKAGE_DOWNLOAD_FAILED");
+    }
+    if (!response.ok ||
+        response.redirected ||
+        response.url !== url.href ||
+        Number(response.headers.get("content-length") ?? 0) > MAX_PACKAGE_BYTES)
+        fail("PACKAGE_DOWNLOAD_FAILED");
+    let bytes;
+    try {
+        bytes = new Uint8Array(await response.arrayBuffer());
+    }
+    catch {
+        fail("PACKAGE_DOWNLOAD_FAILED");
+    }
+    if (bytes.length > MAX_PACKAGE_BYTES)
+        fail("PACKAGE_DOWNLOAD_FAILED");
+    return bytes;
+}
+export async function prepareIndependentSkill(options) {
+    const ordered = resolve(options.index, options.skillId, options.skillVersion, options.rootSkillVersion, options.platformVersion);
+    if (!path.isAbsolute(options.codexHome))
+        fail("INSTALL_PATH_UNSAFE");
+    const skillsRoot = path.join(options.codexHome, "skills");
+    const stateRoot = path.join(options.codexHome, ".nggaigc-managed");
+    await mkdir(skillsRoot, { recursive: true });
+    await mkdir(stateRoot, { recursive: true });
+    if ((await realpath(skillsRoot)) !== path.resolve(skillsRoot))
+        fail("INSTALL_PATH_UNSAFE");
+    if ((await realpath(stateRoot)) !== path.resolve(stateRoot))
+        fail("INSTALL_PATH_UNSAFE");
+    const fetcher = options.fetcher ?? fetch;
+    let result;
+    for (const entry of ordered) {
+        const slug = entry.id.slice("skill.".length);
+        if (slug === "nggaigc")
+            fail("INSTALL_CONFLICT");
+        const target = path.join(skillsRoot, slug);
+        const lock = path.join(stateRoot, `.nggaigc-${slug}.lock`);
+        let handle;
+        try {
+            handle = await open(lock, "wx", 0o600);
+        }
+        catch {
+            fail("INSTALL_BUSY");
+        }
+        try {
+            const backup = path.join(stateRoot, `.nggaigc-backup-${slug}`);
+            if ((await lstat(backup).then(() => true, () => false)) &&
+                !(await lstat(target).then(() => true, () => false))) {
+                let version;
+                try {
+                    const receipt = JSON.parse(await readFile(path.join(backup, ".nggaigc-package.json"), "utf8"));
+                    if (!record(receipt) || typeof receipt.version !== "string")
+                        fail("ROLLBACK_PENDING");
+                    version = receipt.version;
+                }
+                catch {
+                    fail("ROLLBACK_PENDING");
+                }
+                const previous = options.index.entries.find((candidate) => candidate.id === entry.id &&
+                    candidate.version === version &&
+                    candidate.state === "active");
+                if (!previous ||
+                    !(await existingReceipt(backup, previous, options.trust)))
+                    fail("ROLLBACK_PENDING");
+                await rename(backup, target);
+            }
+            if (await existingReceipt(target, entry, options.trust)) {
+                result = {
+                    id: entry.id,
+                    version: entry.version,
+                    skillPath: path.join(target, "SKILL.md"),
+                    reused: true,
+                };
+                continue;
+            }
+            const bytes = await download(entry, options.index.releaseId, options.origin ?? "https://api.nggaigc.com/", fetcher);
+            const files = decodePackage(bytes, entry, options.trust);
+            const stage = path.join(stateRoot, `.nggaigc-stage-${slug}-${randomUUID()}`);
+            await mkdir(stage);
+            try {
+                for (const file of files) {
+                    const destination = path.join(stage, ...file.path.split("/"));
+                    await mkdir(path.dirname(destination), { recursive: true });
+                    await writeFile(destination, Buffer.from(file.contentBase64, "base64"), { flag: "wx", mode: 0o600 });
+                }
+                await writeFile(path.join(stage, ".nggaigc-package.json"), `${JSON.stringify({ id: entry.id, version: entry.version, sha256: entry.manifest.package.sha256, manifestSha256: entry.manifestSha256, releaseId: options.index.releaseId, files: Object.fromEntries(files.map((file) => [file.path, file.sha256])) })}\n`, { flag: "wx", mode: 0o600 });
+                await writeFile(path.join(stage, ".nggaigc-package.bin"), bytes, {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+                const targetExists = await lstat(target).then(() => true, () => false);
+                if (targetExists) {
+                    let oldReceipt;
+                    try {
+                        const value = JSON.parse(await readFile(path.join(target, ".nggaigc-package.json"), "utf8"));
+                        if (!record(value) ||
+                            typeof value.id !== "string" ||
+                            typeof value.version !== "string")
+                            fail("INSTALL_CONFLICT");
+                        oldReceipt = { id: value.id, version: value.version };
+                    }
+                    catch {
+                        fail("INSTALL_CONFLICT");
+                    }
+                    const oldEntry = options.index.entries.find((candidate) => candidate.id === oldReceipt.id &&
+                        candidate.version === oldReceipt.version);
+                    if (oldReceipt.id !== entry.id ||
+                        !oldEntry ||
+                        !(await existingReceipt(target, oldEntry, options.trust)))
+                        fail("INSTALL_CONFLICT");
+                    if (await lstat(backup).then(() => true, () => false))
+                        fail("ROLLBACK_PENDING");
+                    await rename(target, backup);
+                }
+                try {
+                    await options.beforeActivate?.();
+                    await rename(stage, target);
+                }
+                catch {
+                    if (targetExists)
+                        await rename(backup, target);
+                    fail("INSTALL_FAILED");
+                }
+                result = {
+                    id: entry.id,
+                    version: entry.version,
+                    skillPath: path.join(target, "SKILL.md"),
+                    reused: false,
+                };
+            }
+            finally {
+                await rm(stage, { recursive: true, force: true });
+            }
+        }
+        finally {
+            await handle.close();
+            await rm(lock, { force: true });
+        }
+    }
+    return result;
+}
+/** Official start path: online server admission must precede any local preparation. */
+export async function startIndependentSkill(options) {
+    const target = resolve(options.index, options.skillId, options.skillVersion, options.rootSkillVersion, options.platformVersion).at(-1);
+    const identity = {
+        kind: "skill",
+        id: target.id,
+        version: target.version,
+        manifestSha256: target.manifestSha256,
+        releaseId: options.index.releaseId,
+    };
+    let admission;
+    try {
+        admission = await options.admit(identity);
+    }
+    catch (error) {
+        if (record(error) && error.code === "INSUFFICIENT_CREDITS")
+            fail("INSUFFICIENT_CREDITS");
+        fail("START_ADMISSION_UNAVAILABLE");
+    }
+    if (admission.status !== "admitted" ||
+        admission.kind !== identity.kind ||
+        admission.id !== identity.id ||
+        admission.version !== identity.version ||
+        admission.manifestSha256 !== identity.manifestSha256 ||
+        admission.releaseId !== identity.releaseId)
+        fail("START_ADMISSION_REJECTED");
+    return prepareIndependentSkill(options);
+}
+export async function rollbackIndependentSkill(options) {
+    const previous = resolve(options.index, options.skillId, options.skillVersion, options.rootSkillVersion, options.platformVersion).at(-1);
+    const current = options.index.entries.find((entry) => entry.id === options.skillId &&
+        entry.version === options.installedVersion);
+    if (!current)
+        fail("ROLLBACK_UNAVAILABLE");
+    if (!path.isAbsolute(options.codexHome))
+        fail("INSTALL_PATH_UNSAFE");
+    const skillsRoot = path.join(options.codexHome, "skills");
+    const stateRoot = path.join(options.codexHome, ".nggaigc-managed");
+    if ((await realpath(skillsRoot).catch(() => "")) !== path.resolve(skillsRoot))
+        fail("INSTALL_PATH_UNSAFE");
+    if ((await realpath(stateRoot).catch(() => "")) !== path.resolve(stateRoot))
+        fail("INSTALL_PATH_UNSAFE");
+    const slug = options.skillId.slice("skill.".length);
+    const target = path.join(skillsRoot, slug);
+    const backup = path.join(stateRoot, `.nggaigc-backup-${slug}`);
+    const lock = path.join(stateRoot, `.nggaigc-${slug}.lock`);
+    let handle;
+    try {
+        handle = await open(lock, "wx", 0o600);
+    }
+    catch {
+        fail("INSTALL_BUSY");
+    }
+    const retired = path.join(stateRoot, `.nggaigc-retired-${slug}-${randomUUID()}`);
+    try {
+        if (!(await existingReceipt(target, current, options.trust)) ||
+            !(await existingReceipt(backup, previous, options.trust)))
+            fail("ROLLBACK_UNAVAILABLE");
+        await rename(target, retired);
+        try {
+            await rename(backup, target);
+        }
+        catch {
+            await rename(retired, target);
+            fail("INSTALL_FAILED");
+        }
+        await rm(retired, { recursive: true });
+        return {
+            id: previous.id,
+            version: previous.version,
+            skillPath: path.join(target, "SKILL.md"),
+            reused: false,
+        };
+    }
+    finally {
+        await handle.close();
+        await rm(lock, { force: true });
+    }
+}