@nggaigc/cli 0.1.53 → 0.1.55

package/dist/root-upgrade.js

@@ -0,0 +1,365 @@
+/** A finite root transaction. It shares the signed installer's lock and keeps verified backups. */
+import { randomBytes } from "node:crypto";
+import { lstat, mkdir, open, readFile, rmdir, rename, rm, readdir, } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { extractBundle, verifyExtractedBundle, verifyInstalledSkill, } from "./bundle.js";
+import { exists, knownBundle, privateDirectory, rootVendor, saveProof, syncDirectory, trustedRoot, } from "./root-store.js";
+const journalName = ".nggaigc-root-upgrade.json";
+const noncePattern = /^[a-f0-9]{32}$/;
+const supported = ["1.1.49", "1.1.50"];
+function fail() {
+    throw new CliError("ROOT_RECOVERY_REQUIRED");
+}
+async function durableJson(file, value) {
+    const fd = await open(file, "wx", 0o600);
+    try {
+        await fd.writeFile(JSON.stringify(value) + "\n");
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+    await syncDirectory(path.dirname(file));
+}
+const acquisitionGateName = ".nggaigc-install-acquire";
+/** No stale-gate reclamation: an interrupted acquisition requires explicit readback. */
+async function acquisitionGate(skills, own) {
+    const directory = path.join(skills, acquisitionGateName);
+    const ownerFile = path.join(directory, "owner.json");
+    try {
+        await mkdir(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        try {
+            const facts = await lstat(directory);
+            const ownerFacts = await lstat(ownerFile);
+            if (!facts.isDirectory() ||
+                facts.isSymbolicLink() ||
+                !ownerFacts.isFile() ||
+                ownerFacts.isSymbolicLink())
+                fail();
+            const prior = JSON.parse(await readFile(ownerFile, "utf8"));
+            if (Object.keys(prior).sort().join(",") !== "nonce,pid,schemaVersion" ||
+                prior.schemaVersion !== "nggaigc-install-acquire/v1" ||
+                !Number.isSafeInteger(prior.pid) ||
+                prior.pid < 1 ||
+                typeof prior.nonce !== "string" ||
+                !noncePattern.test(prior.nonce))
+                fail();
+            try {
+                process.kill(prior.pid, 0);
+            }
+            catch (signal) {
+                if (signal.code === "ESRCH")
+                    fail();
+            }
+        }
+        catch (cause) {
+            if (cause instanceof CliError)
+                throw cause;
+            fail();
+        }
+        throw new CliError("INSTALL_BUSY");
+    }
+    const identity = await lstat(directory);
+    // A failure before this write completes leaves the gate in place, never guessed away.
+    await durableJson(ownerFile, {
+        ...own,
+        schemaVersion: "nggaigc-install-acquire/v1",
+    });
+    await syncDirectory(skills);
+    return async () => {
+        const facts = await lstat(directory);
+        const ownerFacts = await lstat(ownerFile);
+        const owner = JSON.parse(await readFile(ownerFile, "utf8"));
+        if (!facts.isDirectory() ||
+            facts.isSymbolicLink() ||
+            facts.ino !== identity.ino ||
+            !ownerFacts.isFile() ||
+            ownerFacts.isSymbolicLink() ||
+            owner.schemaVersion !== "nggaigc-install-acquire/v1" ||
+            owner.pid !== own.pid ||
+            owner.nonce !== own.nonce ||
+            (await readdir(directory)).join(",") !== "owner.json")
+            fail();
+        await rm(ownerFile);
+        await rmdir(directory);
+        await syncDirectory(skills);
+    };
+}
+export async function withRootLock(skills, action) {
+    await privateDirectory(skills);
+    const lock = path.join(skills, ".nggaigc-install.lock");
+    const own = {
+        schemaVersion: "nggaigc-install-lock/v2",
+        pid: process.pid,
+        nonce: randomBytes(16).toString("hex"),
+    };
+    // Every 055 creator/reclaimer takes this atomic gate before touching the main
+    // lock. A delayed stale snapshot cannot unlink another 055 owner's live lock.
+    const releaseGate = await acquisitionGate(skills, own);
+    let fd;
+    try {
+        try {
+            try {
+                fd = await open(lock, "wx", 0o600);
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                const before = await lstat(lock);
+                if (!before.isFile() || before.isSymbolicLink())
+                    throw new CliError("INSTALL_BUSY");
+                let prior;
+                try {
+                    prior = JSON.parse(await readFile(lock, "utf8"));
+                }
+                catch {
+                    throw new CliError("INSTALL_BUSY");
+                }
+                if (Object.keys(prior).sort().join(",") !== "nonce,pid,schemaVersion" ||
+                    !["nggaigc-install-lock/v1", own.schemaVersion].includes(prior.schemaVersion) ||
+                    !Number.isSafeInteger(prior.pid) ||
+                    prior.pid < 1 ||
+                    typeof prior.nonce !== "string" ||
+                    !noncePattern.test(prior.nonce))
+                    throw new CliError("INSTALL_BUSY");
+                try {
+                    process.kill(prior.pid, 0);
+                    throw new CliError("INSTALL_BUSY");
+                }
+                catch (signal) {
+                    if (signal.code !== "ESRCH")
+                        throw new CliError("INSTALL_BUSY");
+                }
+                // A v1 observer may already hold a stale snapshot and ignores our gate.
+                // Never replace a dead v1 lock automatically; require quiescent recovery.
+                if (prior.schemaVersion !== own.schemaVersion)
+                    fail();
+                const again = await lstat(lock);
+                if (again.ino !== before.ino ||
+                    again.size !== before.size ||
+                    again.mtimeMs !== before.mtimeMs)
+                    throw new CliError("INSTALL_BUSY");
+                await rm(lock);
+                try {
+                    fd = await open(lock, "wx", 0o600);
+                }
+                catch {
+                    throw new CliError("INSTALL_BUSY");
+                }
+            }
+            await fd.writeFile(JSON.stringify(own) + "\n");
+            await fd.sync();
+            await syncDirectory(skills);
+        }
+        finally {
+            // Release only the short acquisition gate. The main lock covers action.
+            // SIGKILL during action therefore leaves the original recoverable lock.
+            await releaseGate();
+        }
+    }
+    catch (error) {
+        await fd?.close();
+        throw error;
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await fd.close();
+        try {
+            const v = JSON.parse(await readFile(lock, "utf8"));
+            if (v.pid === own.pid && v.nonce === own.nonce) {
+                await rm(lock);
+                await syncDirectory(skills);
+            }
+        }
+        catch {
+            /* Never remove an untrusted replacement. */
+        }
+    }
+}
+function paths(skills, j) {
+    return {
+        target: path.join(skills, "nggaigc"),
+        stage: path.join(skills, `.nggaigc-verified-stage-${j.nonce}`),
+        backup: path.join(skills, `.nggaigc-verified-backup-${j.nonce}`),
+        rejected: path.join(skills, `.nggaigc-verified-rejected-${j.nonce}`),
+    };
+}
+async function valid(directory, bundle) {
+    try {
+        await verifyInstalledSkill(directory, bundle.files, bundle.executableFiles);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function finish(skills, j, outcome) {
+    const done = path.join(skills, `.nggaigc-root-${outcome}-${j.nonce}.json`);
+    if (await exists(done))
+        fail();
+    await rename(path.join(skills, journalName), done);
+    await syncDirectory(skills);
+}
+/** Call only while holding withRootLock. Recovery observes the original journal, never starts a new transaction. */
+export async function recoverRoot(skills, vendor = rootVendor) {
+    const file = path.join(skills, journalName);
+    if (!(await exists(file)))
+        return;
+    const info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink())
+        fail();
+    let j;
+    try {
+        j = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        fail();
+    }
+    if (Object.keys(j).sort().join(",") !==
+        "archiveSha256,from,nonce,schemaVersion,to" ||
+        j.schemaVersion !== "nggaigc-root-upgrade/v1" ||
+        !noncePattern.test(j.nonce) ||
+        !supported.includes(j.to) ||
+        (j.from !== null && !supported.includes(j.from)) ||
+        j.from === j.to ||
+        !/^[a-f0-9]{64}$/.test(j.archiveSha256))
+        fail();
+    const p = paths(skills, j), next = await knownBundle(skills, j.to, vendor);
+    if (next.sha256 !== j.archiveSha256)
+        fail();
+    if (await valid(p.target, next)) {
+        await finish(skills, j, "committed");
+        return "committed";
+    }
+    if (j.from !== null) {
+        const previous = await knownBundle(skills, j.from, vendor);
+        if (await valid(p.target, previous)) {
+            await finish(skills, j, "restored");
+            return "restored";
+        }
+        if (!(await valid(p.backup, previous)))
+            fail();
+        if (await exists(p.target)) {
+            if (await exists(p.rejected))
+                fail();
+            await rename(p.target, p.rejected);
+            await syncDirectory(skills);
+        }
+        await rename(p.backup, p.target);
+        await syncDirectory(skills);
+        await verifyInstalledSkill(p.target, previous.files, previous.executableFiles);
+        await finish(skills, j, "restored");
+        return "restored";
+    }
+    // A first installation has no previous state. Only its fully verified stage may be committed.
+    if ((await exists(p.target)) || !(await valid(p.stage, next)))
+        fail();
+    await rename(p.stage, p.target);
+    await syncDirectory(skills);
+    await verifyInstalledSkill(p.target, next.files, next.executableFiles);
+    await finish(skills, j, "committed");
+    return "committed";
+}
+export async function recoverRootForUse(skills, vendor = rootVendor) {
+    if ((await recoverRoot(skills, vendor)) === "restored")
+        throw new CliError("ROOT_UPGRADE_RESTORED");
+}
+/** Caller holds the shared lock. No signed source, credential or run state is changed. */
+export async function installVerifiedRootLocked(skills, bundle, options = {}) {
+    const vendor = options.vendor ?? rootVendor;
+    await recoverRootForUse(skills, vendor);
+    for (const name of await readdir(skills))
+        if (/^\.nggaigc-pair(?:-v[23])?-(?:transaction|stage)/.test(name))
+            throw new CliError("SKILL_PAIR_RECOVERY_REQUIRED");
+    const target = path.join(skills, "nggaigc");
+    const old = (await exists(target)) ? await trustedRoot(skills, vendor) : null;
+    if (old?.version === bundle.version)
+        return "unchanged";
+    if (!supported.includes(bundle.version) ||
+        (old && !supported.includes(old.version)))
+        throw new CliError("ROOT_UNAVAILABLE");
+    if (old)
+        await saveProof(skills, old.bundle, vendor);
+    await saveProof(skills, bundle, vendor);
+    const j = {
+        schemaVersion: "nggaigc-root-upgrade/v1",
+        nonce: randomBytes(16).toString("hex"),
+        from: old?.version ?? null,
+        to: bundle.version,
+        archiveSha256: bundle.sha256,
+    };
+    const p = paths(skills, j), extracted = path.join(skills, `.nggaigc-verified-source-${j.nonce}`);
+    try {
+        await extractBundle(bundle.archive, extracted, bundle.sha256);
+        await verifyExtractedBundle(extracted, bundle.files);
+        const require = createRequire(import.meta.url);
+        const installer = require(path.join(extracted, "installer/install.cjs"));
+        if (typeof installer.copyTree !== "function")
+            throw new CliError("PACKAGE_VERIFICATION_FAILED");
+        await mkdir(p.stage, { mode: 0o700 });
+        await installer.copyTree(path.join(extracted, "skills/nggaigc"), p.stage);
+        await durableJson(path.join(p.stage, ".nggaigc-install.json"), {
+            schemaVersion: "nggaigc-local-install/v1",
+            version: bundle.version,
+            installedAt: new Date().toISOString(),
+        });
+        await options.step?.("stage-copied", p);
+        await verifyInstalledSkill(p.stage, bundle.files, bundle.executableFiles);
+        // Flush all payloads before recording intent; directory renames then survive process interruption.
+        for (const name of Object.keys(bundle.files).filter((x) => x.startsWith("skills/nggaigc/"))) {
+            const fd = await open(path.join(p.stage, name.slice(15)), "r");
+            try {
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+        }
+        const syncTree = async (directory) => {
+            for (const entry of await readdir(directory, { withFileTypes: true }))
+                if (entry.isDirectory())
+                    await syncTree(path.join(directory, entry.name));
+            await syncDirectory(directory);
+        };
+        await syncTree(p.stage);
+        await durableJson(path.join(skills, journalName), j);
+        if (old) {
+            await verifyInstalledSkill(target, old.bundle.files, old.bundle.executableFiles);
+            await rename(target, p.backup);
+            await syncDirectory(skills);
+            await options.step?.("old-renamed", p);
+        }
+        await rename(p.stage, target);
+        await syncDirectory(skills);
+        await options.step?.("new-renamed", p);
+        await verifyInstalledSkill(target, bundle.files, bundle.executableFiles);
+        await options.step?.("post-verified", p);
+        await finish(skills, j, "committed");
+        return old ? "updated" : "installed";
+    }
+    catch (error) {
+        if (await exists(path.join(skills, journalName))) {
+            try {
+                await recoverRoot(skills, vendor);
+            }
+            catch {
+                throw new CliError("ROOT_RECOVERY_REQUIRED");
+            }
+        }
+        throw error;
+    }
+    finally {
+        await rm(extracted, { recursive: true, force: true });
+    }
+}
+export async function ensureCurrentRootLocked(skills, vendor = rootVendor) {
+    await installVerifiedRootLocked(skills, await knownBundle(skills, "1.1.50", vendor), { vendor });
+}

package/dist/skill-command.js

@@ -4,30 +4,32 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveSkillLocation, } from "./skill-location.js";
-import { trustedKeyId, trustedKeySpkiSha256, verifyBundle, verifyInstalledSkill, } from "./bundle.js";
+import { CliError } from "./errors.js";
+import { trustedKeyId, trustedKeySpkiSha256 } from "./bundle.js";
+import { trustedRoot, trustedRuntime, exists } from "./root-store.js";
+import { withRootLock, recoverRootForUse, ensureCurrentRootLocked, } from "./root-upgrade.js";
+import { canonical, resolveStartAlias } from "./start-compatibility.js";
 import { IndependentSkillError, projectActiveSkillCatalog, startIndependentSkill, } from "./independent-skill.js";
+function compare(a, b) {
+    const x = a.split(".").map(Number), y = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = x[i] - y[i];
+        if (d)
+            return d;
+    }
+    return 0;
+}
 function fail(code) {
     throw new IndependentSkillError(code);
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-export async function productionDependencies(skillsDirectory) {
+async function productionDependenciesLocked(skillsDirectory, verifiedLauncher, runtimeVersion, createRuntime = true) {
     const vendor = fileURLToPath(new URL("../vendor/", import.meta.url));
-    const bundle = await verifyBundle({
-        archive: path.join(vendor, "nggaigc-plugin-1.1.49.zip"),
-        manifest: path.join(vendor, "manifest.json"),
-        trust: path.join(vendor, "trusted-keys.json"),
-    });
-    const root = path.join(skillsDirectory, "nggaigc");
-    await verifyInstalledSkill(root, bundle.files);
-    const source = JSON.parse(await readFile(path.join(root, "references", "source.json"), "utf8"));
-    if (!record(source) ||
-        source.id !== "skill.nggaigc" ||
-        typeof source.version !== "string" ||
-        !/^\d+\.\d+\.\d+$/.test(source.version) ||
-        source.clientProtocol !== 1)
-        fail("ROOT_UNAVAILABLE");
+    const current = await trustedRoot(skillsDirectory);
+    const installed = await trustedRuntime(skillsDirectory, runtimeVersion ?? current.version, undefined, createRuntime);
+    const root = installed.directory;
     const keys = JSON.parse(await readFile(path.join(vendor, "trusted-keys.json"), "utf8"));
     if (!record(keys) ||
         keys.schemaVersion !== "ngg-trusted-package-keys/v1" ||
@@ -45,30 +47,108 @@ export async function productionDependencies(skillsDirectory) {
     if (fingerprint !== trustedKeySpkiSha256)
         fail("TRUST_UNAVAILABLE");
     const require = createRequire(import.meta.url);
+    for (const cached of Object.keys(require.cache))
+        if (cached.startsWith(root + path.sep))
+            delete require.cache[cached];
     const launcher = require(path.join(root, "scripts", "launch-ngg-client.cjs"));
     if (!record(launcher) || typeof launcher.main !== "function")
         fail("ROOT_UNAVAILABLE");
     return {
-        launcher: launcher,
+        launcher: verifiedLauncher?.({ version: installed.version, directory: root }) ??
+            launcher,
         trust: {
             keyId: trustedKeyId,
             publicKeyPem: match.publicKeyPem,
             spkiSha256: fingerprint,
         },
-        rootSkillVersion: source.version,
+        rootSkillVersion: installed.version,
+        rootLauncherPath: path.join(root, "scripts/launch-ngg-client.cjs"),
     };
 }
+/** Read-only fast path for existing immutable runtimes; only recovery/cache creation locks. */
+export async function productionDependencies(skillsDirectory, verifiedLauncher, runtimeVersion) {
+    if (!(await exists(path.join(skillsDirectory, ".nggaigc-root-upgrade.json")))) {
+        try {
+            return await productionDependenciesLocked(skillsDirectory, verifiedLauncher, runtimeVersion, false);
+        }
+        catch (error) {
+            if (!(error instanceof CliError) ||
+                error.code !== "ROOT_RUNTIME_UNAVAILABLE")
+                throw error;
+        }
+    }
+    return withRootLock(skillsDirectory, async () => {
+        await recoverRootForUse(skillsDirectory);
+        return productionDependenciesLocked(skillsDirectory, verifiedLauncher, runtimeVersion, true);
+    });
+}
+async function upgradeRoot(skillsDirectory) {
+    await withRootLock(skillsDirectory, () => ensureCurrentRootLocked(skillsDirectory));
+}
+function catalogRootVersion(snapshot) {
+    if (!record(snapshot) || !Array.isArray(snapshot.entries))
+        fail("CATALOG_INVALID");
+    const roots = snapshot.entries.filter((e) => record(e) &&
+        e.id === "skill.nggaigc" &&
+        record(e.manifest) &&
+        e.manifest.role === "root_skill" &&
+        record(e.manifest.lifecycle) &&
+        e.manifest.lifecycle.status === "published");
+    if (roots.length !== 1 ||
+        !["1.1.49", "1.1.50"].includes(String(roots[0].version)))
+        fail("ROOT_UNAVAILABLE");
+    return String(roots[0].version);
+}
 /** Generic bridge only: the verified launcher owns command and API contracts. */
 export async function runClientCommand(args, options = {}, launcherOptions = {}) {
     if (args.length === 0)
         fail("INVALID_INPUT");
     const { skillsDirectory } = resolveSkillLocation(options);
-    const { launcher } = await productionDependencies(skillsDirectory);
-    return launcher.main(args, launcherOptions);
+    const execute = async () => {
+        let { launcher, rootSkillVersion } = await productionDependencies(skillsDirectory, options.verifiedLauncher);
+        if ([
+            "preflight",
+            "connect",
+            "reconnect",
+            "login",
+            "relogin",
+            "status",
+            "disconnect",
+        ].includes(args[0]))
+            return launcher.main(args, launcherOptions);
+        // Catalog read is a generic bootstrap operation. Login/offline diagnostics may
+        // continue when it is unavailable; all remote actions retain server admission.
+        let snapshot;
+        try {
+            snapshot = await launcher.main(["catalog-snapshot"], launcherOptions);
+        }
+        catch {
+            /* Keep the existing connection/recovery contract. */
+        }
+        if (snapshot !== undefined) {
+            projectActiveSkillCatalog(snapshot);
+            if (!record(snapshot) || !Array.isArray(snapshot.entries))
+                fail("CATALOG_INVALID");
+            const target = catalogRootVersion(snapshot);
+            if (target !== rootSkillVersion) {
+                if (compare(target, rootSkillVersion) > 0)
+                    await upgradeRoot(skillsDirectory);
+                const updated = await productionDependencies(skillsDirectory, options.verifiedLauncher, target);
+                launcher = updated.launcher;
+                const fresh = await launcher.main(["catalog-snapshot"], launcherOptions);
+                projectActiveSkillCatalog(fresh);
+                if (canonical(fresh) !== canonical(snapshot))
+                    fail("CATALOG_CHANGED");
+            }
+        }
+        return launcher.main(args, launcherOptions);
+    };
+    return execute();
 }
 /** Candidate npm entry: active catalog → server admission → verified local Skill path. */
 export async function runSkillStartCommand(skillId, skillVersion, options = {}) {
-    if (!/^skill\.[a-z0-9][a-z0-9.-]{0,79}$/.test(skillId) ||
+    if ((options.exactVersion && skillVersion === undefined) ||
+        !/^skill\.[a-z0-9][a-z0-9.-]{0,79}$/.test(skillId) ||
         (skillVersion !== undefined && !/^\d+\.\d+\.\d+$/.test(skillVersion)))
         fail("INVALID_INPUT");
     const configuredDirectory = resolveSkillLocation(options).skillsDirectory;
@@ -77,53 +157,78 @@ export async function runSkillStartCommand(skillId, skillVersion, options = {})
             ? configuredDirectory
             : fail("INSTALL_PATH_UNSAFE"))
         : configuredDirectory;
-    const production = options.launcher && options.trust && options.rootSkillVersion
-        ? null
-        : await productionDependencies(skillsDirectory);
-    const launcher = options.launcher ?? production.launcher;
-    const trust = options.trust ?? production.trust;
-    const rootSkillVersion = options.rootSkillVersion ?? production.rootSkillVersion;
-    const platformVersion = options.platformVersion ??
-        JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
-    let snapshot;
-    try {
-        snapshot = await launcher.main(["catalog-snapshot"]);
-    }
-    catch {
-        fail("CATALOG_UNAVAILABLE");
-    }
-    const index = projectActiveSkillCatalog(snapshot);
-    const matches = index.entries.filter((entry) => entry.id === skillId &&
-        entry.state === "active" &&
-        entry.sourceManifest?.role === "independent_skill" &&
-        (skillVersion === undefined || entry.version === skillVersion));
-    if (matches.length !== 1)
-        fail("SKILL_UNAVAILABLE");
-    const selected = matches[0];
-    const result = await startIndependentSkill({
-        index,
-        skillId: selected.id,
-        skillVersion: selected.version,
-        rootSkillVersion,
-        platformVersion,
-        skillsDirectory,
-        trust,
-        fetcher: options.fetcher,
-        admit: async (identity) => {
-            const answer = await launcher.main([
-                "skill-admit",
-                identity.kind,
-                identity.id,
-                identity.version,
-                identity.manifestSha256,
-                identity.releaseId,
-            ]);
-            return answer;
-        },
-    });
-    return {
-        ...result,
-        skillsDirectory,
-        rootLauncherPath: path.join(skillsDirectory, "nggaigc", "scripts", "launch-ngg-client.cjs"),
+    const execute = async () => {
+        const production = options.launcher && options.trust && options.rootSkillVersion
+            ? null
+            : await productionDependencies(skillsDirectory, options.verifiedLauncher);
+        let launcher = options.launcher ?? production.launcher;
+        const trust = options.trust ?? production.trust;
+        let rootSkillVersion = options.rootSkillVersion ?? production.rootSkillVersion;
+        const platformVersion = options.platformVersion ??
+            JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+        let snapshot;
+        try {
+            snapshot = await launcher.main(["catalog-snapshot"], options.launcherOptions);
+        }
+        catch {
+            fail("CATALOG_UNAVAILABLE");
+        }
+        const index = projectActiveSkillCatalog(snapshot);
+        const migration = await resolveStartAlias(snapshot, index, skillId, skillVersion, options.migrationTrust ?? trust, options);
+        const resolvedVersion = migration?.toVersion ?? skillVersion;
+        const matches = index.entries.filter((entry) => entry.id === skillId &&
+            entry.state === "active" &&
+            entry.sourceManifest?.role === "independent_skill" &&
+            (resolvedVersion === undefined || entry.version === resolvedVersion));
+        if (matches.length !== 1)
+            fail("SKILL_UNAVAILABLE");
+        const selected = matches[0];
+        let rootLauncherPath = production?.rootLauncherPath ??
+            path.join(skillsDirectory, "nggaigc/scripts/launch-ngg-client.cjs");
+        if (production) {
+            const target = catalogRootVersion(snapshot);
+            if (target !== rootSkillVersion) {
+                if (compare(target, rootSkillVersion) > 0)
+                    await upgradeRoot(skillsDirectory);
+                const updated = await productionDependencies(skillsDirectory, options.verifiedLauncher, target);
+                launcher = updated.launcher;
+                rootSkillVersion = updated.rootSkillVersion;
+                rootLauncherPath = updated.rootLauncherPath;
+                const fresh = await launcher.main(["catalog-snapshot"], options.launcherOptions);
+                projectActiveSkillCatalog(fresh);
+                if (canonical(fresh) !== canonical(snapshot))
+                    fail("CATALOG_CHANGED");
+            }
+        }
+        const result = await startIndependentSkill({
+            index,
+            skillId: selected.id,
+            skillVersion: selected.version,
+            rootSkillVersion,
+            platformVersion,
+            skillsDirectory,
+            trust,
+            fetcher: options.fetcher,
+            admit: async (identity) => {
+                const answer = await launcher.main([
+                    "skill-admit",
+                    identity.kind,
+                    identity.id,
+                    identity.version,
+                    identity.manifestSha256,
+                    identity.releaseId,
+                ], options.launcherOptions);
+                return answer;
+            },
+        });
+        return {
+            ...result,
+            ...(skillVersion
+                ? { requestedVersion: skillVersion, resolvedVersion: selected.version }
+                : {}),
+            skillsDirectory,
+            rootLauncherPath,
+        };
     };
+    return execute();
 }