@nggaigc/cli 0.1.54 → 0.1.56

package/README.md

@@ -12,7 +12,15 @@ CLI 保留 macOS npm symlink 入口与 packed-TGZ launcher 检查，并验证随
 
 从 CLI `0.1.52` 起，Intel Mac 仅放开安装限制，安装的签名包与 macOS 辅助程序字节保持不变；未做 Intel 兼容性适配或真机验收，不保证登录及工作流可用，运行失败按原有机制报告。实际公开版本和 `@latest` 状态以 npm registry 为准，Apple Silicon 真机验收需单独进行。
 
-CLI `0.1.53` 随包安装已签名的 NGGAIGC 根 Skill `1.1.49`，保留豆包工作识别和 Intel Mac 安装放行；后续独立工作流仍经当前目录解析、在线准入和签名验签加载。
+CLI `0.1.56` 延续 `0.1.55` 的版本兼容修复，实际公开版本与 `latest` 以 registry 为准。它通过官方签名 ZIP 的完整文件闭包识别现有根 Skill `1.1.49`／`1.1.50`；本地安装标记仅作提示。兼容时直接复用现有启动器，当前目录确实要求新版根时才安全升级；不会降级已验证的新版安装。旧目录仍使用根149时，保留已装150，并在不可发现为 active Skill 的私有缓存内验证、使用官方149兼容运行文件；目录切到新版后使用150，启动回执指向实际受信运行文件。保留豆包工作识别和 Intel Mac 安装放行的原边界。
+
+升级在原安装锁内先验证私有临时目录的文件类型、哈希和系统可表达的执行位，再原子替换并复验。失败时恢复已验证旧安装；进程中断后先按原事务读回恢复，不盲目开始新升级。Windows 不把 POSIX 执行位当作其系统权限证明，真机验收另记。
+
+CLI `0.1.56` 修复 Windows 写盘句柄：校验缓存和升级暂存文件使用不截断文件的读写句柄执行 `fsync`，保留验签和失败停止。更新已发布安装器时，使用 `npx --yes @nggaigc/cli@0.1.56 install`；项目级或指定宿主安装保留原命令中的 `--skills-dir` 或 `--agent`，不要另换目录、删除配置或重提已有付费任务。发布状态以 npm 为准。本次原生 Windows 实测尚未完成，不能把模拟回归或 Mac 验收视为 Windows 已通过。维护者在原生 Windows 的 Node 22、24 上构建后，必须分别运行 `node --test packages/cli/scripts/windows-root-flush.integration.test.mjs`，覆盖新装、149→150 升级、重复安装及失败恢复；非 Windows 环境会明确拒绝该验收。模拟约束的回归测试不能代替此项。
+
+旧的显式 `start-skill skill.<id> <version>` 只有在官方受签、精确绑定当前目录的有限迁移许可内，才可转到同一 Skill 的当前版本；结果分别返回 `requestedVersion` 与 `resolvedVersion`，在线准入使用真实新版本及哈希。未列版本、目录变化、停用或验签失败均停止。确需固定版本可加 `--exact-version`，此时绝不迁移到其他版本。无版本调用仍要求唯一 active 入口，不激活旧版本。
+
+此许可仅用于新启动。已经受理或结果未知的任务保留原请求和任务身份；`client` 将原参数交给已验证启动器，不为恢复任务重新准入、提交或付费。
 
 ## 统一安装入口（0.1.46 起）
 

package/dist/bundle.js

@@ -36,8 +36,13 @@ async function json(file) {
         throw new CliError("PACKAGE_VERIFICATION_FAILED");
     }
 }
-export async function verifyBundle(input) {
+export async function verifyBundle(input, expectedVersion = "1.1.50") {
     try {
+        for (const file of [input.archive, input.manifest, input.trust]) {
+            const info = await lstat(file);
+            if (!info.isFile() || info.isSymbolicLink())
+                throw new Error();
+        }
         const manifestValue = await json(input.manifest);
         const trustValue = await json(input.trust);
         const signature = record(manifestValue)
@@ -47,7 +52,7 @@ export async function verifyBundle(input) {
             !exactKeys(manifestValue, manifestKeys) ||
             manifestValue.schemaVersion !== "nggaigc-plugin-package/v1" ||
             manifestValue.artifactId !== "plugin.nggaigc" ||
-            manifestValue.version !== "1.1.50" ||
+            manifestValue.version !== expectedVersion ||
             manifestValue.artifactPath !==
                 `packages/plugins/nggaigc-plugin-${manifestValue.version}.zip` ||
             typeof manifestValue.sourceCommit !== "string" ||
@@ -120,6 +125,22 @@ export async function verifyBundle(input) {
         if (!record(pluginMetadata) ||
             pluginMetadata.version !== manifestValue.version)
             throw new Error();
+        const rootSource = contents.find((entry) => entry.name === "skills/nggaigc/references/source.json");
+        const rootBootstrap = contents.find((entry) => entry.name === "skills/nggaigc/scripts/bootstrap-public.json");
+        const sourceIdentity = rootSource
+            ? JSON.parse(rootSource.bytes.toString("utf8"))
+            : null;
+        const bootstrapIdentity = rootBootstrap
+            ? JSON.parse(rootBootstrap.bytes.toString("utf8"))
+            : null;
+        if (!record(sourceIdentity) ||
+            sourceIdentity.id !== "skill.nggaigc" ||
+            sourceIdentity.version !== manifestValue.version ||
+            sourceIdentity.clientProtocol !== 1 ||
+            !record(bootstrapIdentity) ||
+            bootstrapIdentity.version !== manifestValue.version ||
+            bootstrapIdentity.credentialTarget !== "NGGAIGC/Codex/v1")
+            throw new Error();
         const supported = contents.find((entry) => entry.name === "skills/nggaigc/scripts/supported-platforms.json");
         if (!supported)
             throw new Error();
@@ -139,6 +160,9 @@ export async function verifyBundle(input) {
             version: manifestValue.version,
             platforms: manifestValue.platforms,
             sha256: manifestValue.sha256,
+            executableFiles: contents
+                .filter((entry) => entry.executable)
+                .map((entry) => entry.name),
         };
     }
     catch (error) {
@@ -213,18 +237,39 @@ export async function verifyExtractedBundle(directory, expected) {
         throw new CliError("PACKAGE_VERIFICATION_FAILED");
     }
 }
-export async function verifyInstalledSkill(directory, bundleFiles) {
+export async function verifyInstalledSkill(directory, bundleFiles, executableFiles) {
     const prefix = "skills/nggaigc/";
     const expected = Object.fromEntries(Object.entries(bundleFiles)
         .filter(([name]) => name.startsWith(prefix))
         .map(([name, digest]) => [name.slice(prefix.length), digest]));
     try {
+        const rootFacts = await lstat(directory);
+        if (!rootFacts.isDirectory() || rootFacts.isSymbolicLink())
+            throw new Error();
         const actual = await entries(directory);
         const allowed = [...Object.keys(expected), ".nggaigc-install.json"].sort();
         if (JSON.stringify(actual) !== JSON.stringify(allowed))
             throw new Error();
+        const checkDirectories = async (parent, prefix = "") => {
+            for (const child of await readdir(parent, { withFileTypes: true }))
+                if (child.isDirectory()) {
+                    const relative = prefix + child.name + "/";
+                    if (!Object.keys(expected).some((name) => name.startsWith(relative)))
+                        throw new Error();
+                    await checkDirectories(path.join(parent, child.name), relative);
+                }
+        };
+        await checkDirectories(directory);
         for (const [name, digest] of Object.entries(expected)) {
-            const bytes = await readFile(path.resolve(directory, ...name.split("/")));
+            const absolute = path.resolve(directory, ...name.split("/"));
+            const facts = await lstat(absolute);
+            if (!facts.isFile() || facts.isSymbolicLink())
+                throw new Error();
+            if (executableFiles &&
+                process.platform !== "win32" &&
+                Boolean(facts.mode & 0o111) !== executableFiles.includes(prefix + name))
+                throw new Error();
+            const bytes = await readFile(absolute);
             if (createHash("sha256").update(bytes).digest("hex") !== digest)
                 throw new Error();
         }

package/dist/install.js

@@ -1,3 +1,4 @@
+import { withRootLock, installVerifiedRootLocked } from "./root-upgrade.js";
 import { createRequire } from "node:module";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import os from "node:os";
@@ -242,7 +243,9 @@ export async function runInstall(options = {}) {
         const installer = require(path.join(extracted, "installer", "install.cjs"));
         if (!installer || typeof installer.main !== "function")
             throw new CliError("INSTALLATION_FAILED");
-        const installation = await installSkill(installer, path.join(extracted, "skills", "nggaigc"), profile, skillsDirectory, bundle.version, bundle.files);
+        const installation = options.bundle
+            ? await installSkill(installer, path.join(extracted, "skills/nggaigc"), profile, skillsDirectory, bundle.version, bundle.files)
+            : await withRootLock(skillsDirectory, () => installVerifiedRootLocked(skillsDirectory, bundle));
         const installedScripts = path.join(skillsDirectory, "nggaigc", "scripts");
         if (options.connect === false)
             return { status: "installed", installation, version: bundle.version };

package/dist/main.js

@@ -27,6 +27,9 @@ const errorMessages = {
     LOCAL_SESSION_FAILED: "本地凭据会话未能完成；请先处理本地错误，不要重复网页授权。",
     LOCAL_SESSION_TIMEOUT: "本地凭据会话超时；请先检查当前本地进程，不要重复网页授权。",
     POWERSHELL_EXECUTION_POLICY_BLOCKED: "Windows 脚本执行受到系统或组织策略限制，设备连接未完成。安装器没有更改执行策略。",
+    ROOT_UPGRADE_RESTORED: "上次升级中断，已恢复并验证旧安装；本次未重新升级或提交任务。请确认恢复结果后再发起新的升级。",
+    ROOT_RECOVERY_REQUIRED: "本地升级状态无法安全恢复，已停止；请保留安装目录和事务记录并联系支持。",
+    INSTALL_BUSY: "同一安装目录正在使用或更新，请等待原操作完成。",
     INSTALLATION_FAILED: "本地安装未完成，请检查现有文件状态后重试。",
     SKILL_PAIR_UPGRADE_REQUIRED: "检测到无法安全配套迁移的本地 Seedream Skill，已停止升级。请保留旧 Skill 和任务文件并联系支持。",
     SKILL_PAIR_RECOVERY_REQUIRED: "检测到本地组合安装中断或目录变化，已停止自动操作。请保留相关目录和任务文件并联系支持。",
@@ -42,7 +45,7 @@ export async function main(args, runtime = {}) {
         output([
             "NGGAIGC CLI",
             "install [--agent codex|workbuddy|doubao-work|universal | --skills-dir <absolute-directory>] [--no-login]",
-            "start-skill skill.<id> [version] [--agent codex|workbuddy|doubao-work|universal | --skills-dir <absolute-directory>]",
+            "start-skill skill.<id> [version] [--exact-version] [--agent codex|workbuddy|doubao-work|universal | --skills-dir <absolute-directory>]",
             "client [--agent codex|workbuddy|doubao-work|universal | --skills-dir <absolute-directory>] -- <command> [arguments]",
             "Default: automatically detect Codex, WorkBuddy or Doubao Work. If unknown or conflicting, select one; non-interactive calls return selection-required (exit 3).",
             "Codex: existing CODEX_HOME is preserved, otherwise ~/.codex/skills. WorkBuddy: its runtime config directory/skills, otherwise ~/.workbuddy/skills; existing legacy ~/.codebuddy installs are reused. Doubao Work: ~/DoubaoWork/skills. Explicit legacy universal/custom targets remain supported.",
@@ -86,7 +89,9 @@ export async function main(args, runtime = {}) {
     }
     let parsed;
     try {
-        parsed = parseSkillLocation(args.slice(1));
+        parsed = parseSkillLocation(args
+            .slice(1)
+            .filter((value) => args[0] !== "start-skill" || value !== "--exact-version"));
     }
     catch {
         errorOutput(`${errorMessages.INVALID_INPUT}\n`);
@@ -94,10 +99,14 @@ export async function main(args, runtime = {}) {
     }
     const parameters = parsed.positional;
     if (args[0] === "start-skill" &&
-        (parameters.length === 1 || parameters.length === 2)) {
+        (parameters.length === 1 || parameters.length === 2) &&
+        (!args.includes("--exact-version") || parameters.length === 2)) {
         try {
             const location = await selectCommandLocation({ ...runtime.skillOptions, ...parsed.location }, runtime.agentSelection);
-            const result = await (runtime.startSkill ?? runSkillStartCommand)(parameters[0], parameters[1], location);
+            const result = await (runtime.startSkill ?? runSkillStartCommand)(parameters[0], parameters[1], {
+                ...location,
+                ...(args.includes("--exact-version") ? { exactVersion: true } : {}),
+            });
             output(`${JSON.stringify({ status: "ready", ...result })}\n`);
             return 0;
         }

package/dist/root-store.js

@@ -0,0 +1,174 @@
+/** Official root material is authenticity evidence; a local marker is only a hint. */
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, readFile, rename, copyFile, open, realpath, rm, } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { verifyBundle, verifyInstalledSkill, extractBundle, verifyExtractedBundle, } from "./bundle.js";
+import { stateDirectoryForSkills } from "./skill-location.js";
+import { CliError } from "./errors.js";
+export const rootVendor = fileURLToPath(new URL("../vendor/", import.meta.url));
+const versionPattern = /^\d+\.\d+\.\d+$/;
+export async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return false;
+        throw e;
+    }
+}
+export async function realDirectory(directory) {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new CliError("INSTALL_PATH_UNSAFE");
+}
+export async function privateDirectory(directory) {
+    if (!(await exists(directory))) {
+        await privateDirectory(path.dirname(directory));
+        await mkdir(directory, { mode: 0o700 });
+    }
+    await realDirectory(directory);
+    if ((await realpath(directory)) !== path.resolve(directory))
+        throw new CliError("INSTALL_PATH_UNSAFE");
+}
+export async function syncDirectory(directory) {
+    if (process.platform === "win32")
+        return; // Windows has no portable fsync(directory).
+    const fd = await open(directory, "r");
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+}
+export function proofDirectory(skills, version) {
+    if (!versionPattern.test(version))
+        throw new CliError("ROOT_UNAVAILABLE");
+    return path.join(stateDirectoryForSkills(skills), "root-proofs", version);
+}
+export function bundleFiles(directory, version, vendor = rootVendor) {
+    return {
+        archive: path.join(directory, `nggaigc-plugin-${version}.zip`),
+        manifest: path.join(directory, "manifest.json"),
+        trust: path.join(vendor, "trusted-keys.json"),
+    };
+}
+export async function knownBundle(skills, version, vendor = rootVendor) {
+    const cache = proofDirectory(skills, version);
+    // An existing corrupt cache is rejected; never silently replace its evidence.
+    if (await exists(cache)) {
+        await realDirectory(cache);
+        if ((await realpath(cache)) !== path.resolve(cache))
+            throw new CliError("INSTALL_PATH_UNSAFE");
+        return verifyBundle(bundleFiles(cache, version, vendor), version);
+    }
+    return verifyBundle(bundleFiles(version === "1.1.50" ? vendor : path.join(vendor, "roots", version), version, vendor), version);
+}
+export async function saveProof(skills, bundle, vendor = rootVendor) {
+    const dest = proofDirectory(skills, bundle.version);
+    if (await exists(dest)) {
+        const prior = await knownBundle(skills, bundle.version, vendor);
+        if (prior.sha256 !== bundle.sha256)
+            throw new CliError("PACKAGE_VERIFICATION_FAILED");
+        return;
+    }
+    const parent = path.dirname(dest);
+    await privateDirectory(parent);
+    const temp = path.join(parent, `.proof-${bundle.version}-${randomBytes(16).toString("hex")}`);
+    await mkdir(temp, { mode: 0o700 });
+    await copyFile(bundle.archive, path.join(temp, `nggaigc-plugin-${bundle.version}.zip`), 1);
+    // The archive-adjacent manifest is already cryptographically validated above.
+    await copyFile(path.join(path.dirname(bundle.archive), "manifest.json"), path.join(temp, "manifest.json"), 1);
+    const verified = await verifyBundle(bundleFiles(temp, bundle.version, vendor), bundle.version);
+    if (verified.sha256 !== bundle.sha256)
+        throw new CliError("PACKAGE_VERIFICATION_FAILED");
+    for (const file of [
+        path.join(temp, `nggaigc-plugin-${bundle.version}.zip`),
+        path.join(temp, "manifest.json"),
+    ]) {
+        // Windows FlushFileBuffers requires a writable handle. r+ preserves bytes
+        // and fails if the already-verified staging file is missing (unlike w).
+        const fd = await open(file, "r+");
+        try {
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    await syncDirectory(temp);
+    await rename(temp, dest);
+    await syncDirectory(parent);
+}
+export async function trustedRoot(skills, vendor = rootVendor) {
+    const root = path.join(skills, "nggaigc");
+    await realDirectory(root);
+    let version;
+    try {
+        version = JSON.parse(await readFile(path.join(root, "references/source.json"), "utf8")).version;
+    }
+    catch {
+        throw new CliError("ROOT_UNAVAILABLE");
+    }
+    if (typeof version !== "string" || !versionPattern.test(version))
+        throw new CliError("ROOT_UNAVAILABLE");
+    const bundle = await knownBundle(skills, version, vendor);
+    await verifyInstalledSkill(root, bundle.files, bundle.executableFiles);
+    // This binds source.json and protocol to the signed payload, regardless of marker.version.
+    return { version: bundle.version, bundle, directory: root };
+}
+/** Creation holds the install lock; verified immutable reuse is read-only. */
+export async function trustedRuntime(skills, version, vendor = rootVendor, create = true) {
+    if (!["1.1.49", "1.1.50"].includes(version))
+        throw new CliError("ROOT_UNAVAILABLE");
+    await trustedRoot(skills, vendor);
+    // Delegates always use an immutable runtime, including the currently installed version.
+    const bundle = await knownBundle(skills, version, vendor);
+    const parent = path.join(stateDirectoryForSkills(skills), "root-runtimes");
+    const directory = path.join(parent, version);
+    if (await exists(directory)) {
+        if ((await realpath(directory)) !== path.resolve(directory))
+            throw new CliError("INSTALL_PATH_UNSAFE");
+        await verifyInstalledSkill(directory, bundle.files, bundle.executableFiles);
+        return { version, bundle, directory };
+    }
+    if (!create)
+        throw new CliError("ROOT_RUNTIME_UNAVAILABLE");
+    await privateDirectory(parent);
+    const temporary = path.join(parent, ".runtime-" + randomBytes(16).toString("hex"));
+    try {
+        await extractBundle(bundle.archive, temporary, bundle.sha256);
+        await verifyExtractedBundle(temporary, bundle.files);
+        const root = path.join(temporary, "skills/nggaigc");
+        const marker = await open(path.join(root, ".nggaigc-install.json"), "wx", 0o600);
+        try {
+            await marker.writeFile(JSON.stringify({
+                schemaVersion: "nggaigc-local-install/v1",
+                version,
+                installedAt: new Date().toISOString(),
+            }) + "\n");
+            await marker.sync();
+        }
+        finally {
+            await marker.close();
+        }
+        await verifyInstalledSkill(root, bundle.files, bundle.executableFiles);
+        if (await exists(directory))
+            throw new CliError("ROOT_RECOVERY_REQUIRED");
+        await rename(root, directory);
+        await syncDirectory(parent);
+        await verifyInstalledSkill(directory, bundle.files, bundle.executableFiles);
+        return { version, bundle, directory };
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export async function bytesHash(file) {
+    return createHash("sha256")
+        .update(await readFile(file))
+        .digest("hex");
+}

package/dist/root-upgrade.js

@@ -0,0 +1,366 @@
+/** 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/"))) {
+            // Flush existing staged payloads without truncating or creating files.
+            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.50.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();
 }

package/dist/start-compatibility.js

@@ -0,0 +1,123 @@
+/** Signed, finite aliases for new starts only. Never used for accepted run recovery. */
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { IndependentSkillError, } from "./independent-skill.js";
+export const startCompatibilityDomain = "NGGAIGC/START-COMPATIBILITY/v1\0";
+export function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    return `{${Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+        .join(",")}}`;
+}
+export function startCompatibilityInput(payload) {
+    return Buffer.from(startCompatibilityDomain + canonical(payload), "utf8");
+}
+function record(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function keys(v, expected) {
+    return Object.keys(v).sort().join(",") === expected.sort().join(",");
+}
+function fail() {
+    throw new IndependentSkillError("START_COMPATIBILITY_INVALID");
+}
+export function verifyStartCompatibility(value, trust) {
+    if (!record(value) ||
+        !keys(value, ["payload", "signature"]) ||
+        !record(value.payload) ||
+        !record(value.signature))
+        fail();
+    const p = value.payload, s = value.signature;
+    if (!keys(p, ["schemaVersion", "catalog", "contract", "aliases"]) ||
+        p.schemaVersion !== "nggaigc-start-compatibility/v1" ||
+        p.contract !== "same-skill-inputs-pricing-permissions" ||
+        !record(p.catalog) ||
+        !keys(p.catalog, ["releaseId", "catalogVersion", "releaseSha256"]) ||
+        typeof p.catalog.releaseId !== "string" ||
+        typeof p.catalog.catalogVersion !== "string" ||
+        typeof p.catalog.releaseSha256 !== "string" ||
+        !/^[a-f0-9]{64}$/.test(p.catalog.releaseSha256) ||
+        !Array.isArray(p.aliases) ||
+        !p.aliases.length ||
+        p.aliases.length > 128)
+        fail();
+    const seen = new Set();
+    for (const a of p.aliases) {
+        if (!record(a) ||
+            !keys(a, [
+                "id",
+                "fromVersion",
+                "fromManifestSha256",
+                "toVersion",
+                "toManifestSha256",
+            ]) ||
+            typeof a.id !== "string" ||
+            !/^skill\.[a-z0-9][a-z0-9.-]{0,79}$/.test(a.id) ||
+            typeof a.fromVersion !== "string" ||
+            typeof a.toVersion !== "string" ||
+            !/^\d+\.\d+\.\d+$/.test(a.fromVersion) ||
+            !/^\d+\.\d+\.\d+$/.test(a.toVersion) ||
+            a.fromVersion === a.toVersion ||
+            typeof a.fromManifestSha256 !== "string" ||
+            typeof a.toManifestSha256 !== "string" ||
+            !/^[a-f0-9]{64}$/.test(a.fromManifestSha256) ||
+            !/^[a-f0-9]{64}$/.test(a.toManifestSha256) ||
+            seen.has(`${a.id}@${a.fromVersion}`))
+            fail();
+        seen.add(`${a.id}@${a.fromVersion}`);
+    }
+    if (!keys(s, ["algorithm", "keyId", "scope", "value"]) ||
+        s.algorithm !== "ed25519" ||
+        s.keyId !== trust.keyId ||
+        s.scope !== "nggaigc-start-compatibility/v1" ||
+        typeof s.value !== "string" ||
+        !/^[A-Za-z0-9+/]{86}==$/.test(s.value))
+        fail();
+    try {
+        const key = createPublicKey(trust.publicKeyPem);
+        if (createHash("sha256")
+            .update(key.export({ type: "spki", format: "der" }))
+            .digest("hex") !== trust.spkiSha256 ||
+            !verify(null, startCompatibilityInput(p), key, Buffer.from(s.value, "base64")))
+            fail();
+    }
+    catch {
+        fail();
+    }
+    return p;
+}
+export async function resolveStartAlias(snapshot, index, id, version, trust, options = {}) {
+    if (version === undefined ||
+        index.entries.some((e) => e.id === id && e.version === version && e.state === "active"))
+        return;
+    if (options.exactVersion)
+        throw new IndependentSkillError("SKILL_UNAVAILABLE");
+    let value = options.migrationPermit;
+    if (value === undefined) {
+        try {
+            value = JSON.parse(await readFile(new URL("../vendor/start-compatibility.json", import.meta.url), "utf8"));
+        }
+        catch {
+            throw new IndependentSkillError("SKILL_UNAVAILABLE");
+        }
+    }
+    const permit = verifyStartCompatibility(value, trust);
+    if (!record(snapshot) ||
+        permit.catalog.releaseId !== snapshot.releaseId ||
+        permit.catalog.catalogVersion !== snapshot.catalogVersion ||
+        permit.catalog.releaseSha256 !== snapshot.releaseSha256)
+        throw new IndependentSkillError("START_COMPATIBILITY_CATALOG_MISMATCH");
+    const aliases = permit.aliases.filter((a) => a.id === id && a.fromVersion === version);
+    if (aliases.length !== 1)
+        throw new IndependentSkillError("SKILL_UNAVAILABLE");
+    const alias = aliases[0], targets = index.entries.filter((e) => e.id === id && e.state === "active");
+    if (targets.length !== 1 ||
+        targets[0].version !== alias.toVersion ||
+        targets[0].manifestSha256 !== alias.toManifestSha256)
+        fail();
+    return alias;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nggaigc/cli",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "Secure NGGAIGC Skill installer for Codex, WorkBuddy and compatible agents.",
   "type": "module",
   "bin": {

package/vendor/roots/1.1.49/manifest.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": "nggaigc-plugin-package/v1",
+  "artifactId": "plugin.nggaigc",
+  "version": "1.1.49",
+  "sourceCommit": "69db1c015defab063dc6ac590c3191c3f2accf13",
+  "artifactPath": "packages/plugins/nggaigc-plugin-1.1.49.zip",
+  "sha256": "8f102ea49ea1123c44d2e199fb6f03a520a85890735a3dc88bbbf9718ec8dc65",
+  "sizeBytes": 508722,
+  "fileCount": 24,
+  "platforms": [
+    "win32-x64",
+    "win32-arm64",
+    "darwin-arm64"
+  ],
+  "files": {
+    ".codex-plugin/plugin.json": "ff760760b31838bcf605fc6239c02dd5efbe08e5c66ca2999ab63a75cf535ef0",
+    "installer/install.cjs": "76f4ed73233fd39900fb0bedbc434dea39e52e6b6b4622f3fd388a5ca09c6f62",
+    "installer/legacy-root-digests.json": "922552646a5aa6cff8616c372912a37b1d5f263351206b85785ed9b2eae31641",
+    "installer/signed-pair-1.1.16.json": "ccb22a90302cc5c9c585067ebc211a27b0c9d8a177c2740a5678a58a3d70bfe9",
+    "installer/signed-pair-1.1.17.json": "a3697506c929aaa085a6d994fc3a1b9a87e522ec6e1e32f3f760e6a534effa2b",
+    "migration/seedream-1.1.3/agents/openai.yaml": "3cbf034ddccd64a7972acd37e7433683a3944f3d8c7b5bdccbbd70e517bf5a8c",
+    "migration/seedream-1.1.3/references/image-generation.md": "208389b3ea4647040232c65a9b91ebcc20787818f57535f16664a7c4db842b3f",
+    "migration/seedream-1.1.3/references/source.json": "75998d079a229435d1097b00bd008703bd38026fc6485c312254925bf55398a8",
+    "migration/seedream-1.1.3/scripts/seedream.mjs": "dcc6af4d945790d9dfd7fac21c60934759d7ac2576a14507d0299f4833942a96",
+    "migration/seedream-1.1.3/SKILL.md": "5c5cf3c2d99376f246425e873c5566436ed528256372ac3208abb60364c4517c",
+    "skills/nggaigc/agents/openai.yaml": "8936d97b9821e687e224e9349cc42be2ee5fc20988562efffbcb70080aedf87c",
+    "skills/nggaigc/references/catalog-and-updates.md": "a43bee94a480aa2bf0b1e7038cee6f27fb86d2bd8fa88a28a63678963d7c1530",
+    "skills/nggaigc/references/source.json": "64ac80a785146b993aace78f00e88bdd6a571957d019f8ac093264f8c59b9210",
+    "skills/nggaigc/scripts/api_client.mjs": "e16bf750a297ef7e88e4843d2fba9c33b412a66516bfe76822d7deec6c153069",
+    "skills/nggaigc/scripts/api_package.mjs": "824ea8f935e2c3aec7ad5ea5c6ad043f1b77ccd9918c86687a9bd61558954fe4",
+    "skills/nggaigc/scripts/bootstrap-public.json": "1c5ef86f600dc35543db9f20fe0142fc97ff7f2940b585eb2a27860e3328e83f",
+    "skills/nggaigc/scripts/launch-ngg-client.cjs": "97c3fb740eba0c0a3dc3ef9f24f3cbb201cd2e1b3209d14b782744bcc083e232",
+    "skills/nggaigc/scripts/macos-keychain": "b0bdf29d14219d38ca18c7e5c599deb0daa8c8ac70b0babbc7d4fb23673079ec",
+    "skills/nggaigc/scripts/macos-keychain.swift": "1b57e74fde66c824fe970547dd8ca0883a3334c34c065e85a8a2a90d4556a7f5",
+    "skills/nggaigc/scripts/ngg_client.mjs": "43ce6697bd15f2bfef089031e33eab73ef1f3883cc724962f1e82731c676ef0c",
+    "skills/nggaigc/scripts/ngg-session.mjs": "dbb69158307e3726a567ae65987f61d6ad15f75e3c6e2d41bf43bc50f15d91ec",
+    "skills/nggaigc/scripts/supported-platforms.json": "ec8b0754c489e04534a1d9880dd6664ba9c5bcd07789e06d138e0923f23575ff",
+    "skills/nggaigc/scripts/windows-credential.ps1": "641888d8c6016bb84f18df19315322ed802c5709fbe5209250eaf1b0ce498aec",
+    "skills/nggaigc/SKILL.md": "8cb3eb8a03cf144ce15fa01d7d342495c2b11ba0f6a0cf61a493e1e43c83a11f"
+  },
+  "signature": {
+    "algorithm": "ed25519",
+    "keyId": "ngg-signing-skill-release-1",
+    "scope": "artifact-bytes",
+    "value": "OTRlG+kA7/YmFdLHqdeGfoDftbYidQFCfZay4RSPWdaNmgpuIy32fT7s/u2GWbkAbUz8L1attssM6IPZUraZAg=="
+  }
+}

package/vendor/start-compatibility.json

@@ -0,0 +1,124 @@
+{
+  "payload": {
+    "schemaVersion": "nggaigc-start-compatibility/v1",
+    "catalog": {
+      "releaseId": "catalog-2026.11.02.3",
+      "catalogVersion": "1.10.168",
+      "releaseSha256": "11fa89a45efc9b859d26ae6398b97b3a7559c1d614eefae3ff59a9403f481950"
+    },
+    "contract": "same-skill-inputs-pricing-permissions",
+    "aliases": [
+      {
+        "id": "skill.h3-aqing-video",
+        "fromVersion": "0.1.3",
+        "fromManifestSha256": "aa9bfafce6e01c47b4d1c55cb4222374b7c86dfd0a7eb9b7fd4f75b8ce6725b3",
+        "toVersion": "0.1.4",
+        "toManifestSha256": "8a6f2c926938bd5e39f06ee8618f6a3618176aebc5d2fe891d0f2f57bb623df2"
+      },
+      {
+        "id": "skill.h3-broll-video-assets",
+        "fromVersion": "0.1.9",
+        "fromManifestSha256": "d4f3a01ce66879e668935af9ccba225ca08ca9b123296e8f7e6144a2beb71674",
+        "toVersion": "0.1.10",
+        "toManifestSha256": "14b2d3996d927f2b3c995c3e827a33e990bcca923aa64f84c905b24b3badcfe4"
+      },
+      {
+        "id": "skill.image-singing-digital-human",
+        "fromVersion": "0.1.3",
+        "fromManifestSha256": "e9ae6ca29c8711afceccd423f260b249c6744582ba98cbcbc5bcfc89187a2c11",
+        "toVersion": "0.1.4",
+        "toManifestSha256": "941ca6ea1cd72540adef38f57f6b09b7e7635c72760f9c4eaa4a92e4fc86465a"
+      },
+      {
+        "id": "skill.image-singing-video",
+        "fromVersion": "0.1.2",
+        "fromManifestSha256": "6ef089b81c8da8a1039faeaff80a4559815e07bf46a11482003a191d8656187d",
+        "toVersion": "0.1.3",
+        "toManifestSha256": "a4ec99e3478b100c4abc1662e6cc01b8e41bb01f6653643d20e9910b8ff8b6c8"
+      },
+      {
+        "id": "skill.knowledge-narration-video",
+        "fromVersion": "0.1.7",
+        "fromManifestSha256": "076755d1414537fc46899cab8bae79c25e3607a923cff9df35c2b55c3f5c1c0b",
+        "toVersion": "0.1.8",
+        "toManifestSha256": "32be1dd0d3b59b575239eaf61a4b78226a17a9db757c1b1eb51559a01f946b15"
+      },
+      {
+        "id": "skill.ngg-depth-dance-copy",
+        "fromVersion": "0.2.1",
+        "fromManifestSha256": "efb34854dd2d5ab5e8d33363ca1ce93c69c7743cac143c16c34c360a8bab89fd",
+        "toVersion": "0.2.2",
+        "toManifestSha256": "6eca6fc0897875ba56c0cb460052f7f490f6833c61164daf3dfc22b4e9530fd9"
+      },
+      {
+        "id": "skill.ngg-drama-workflow",
+        "fromVersion": "0.3.4",
+        "fromManifestSha256": "04fdfac21e7010b4268e02b3d2424d9fb1b9359e88461464967565a09e8ec196",
+        "toVersion": "0.3.5",
+        "toManifestSha256": "1e94cabce4f46f7c4dec439e18ec66b19274a71516384379f92477e67275ca88"
+      },
+      {
+        "id": "skill.video-lipsync",
+        "fromVersion": "0.1.1",
+        "fromManifestSha256": "4d4ed19d17c56a0de549e1516c76b1c359749bfcd39dd52b7b24f216d5b68733",
+        "toVersion": "0.1.2",
+        "toManifestSha256": "cce3409eba007acb6901cf01cf5bf57167fa04b22f903aaa600de71ee77d7e4d"
+      },
+      {
+        "id": "skill.video-lipsync-workflow",
+        "fromVersion": "0.1.1",
+        "fromManifestSha256": "b22a9f7b107d9dd1d10be530cd31d6b207f5efa96628793987d7c3aeb3b26b1f",
+        "toVersion": "0.1.2",
+        "toManifestSha256": "a5f8e045e01dcff66cf1f65ab0f831d5349909606a47b4e2fe793c6d6a5cd5c2"
+      },
+      {
+        "id": "skill.voice-clone",
+        "fromVersion": "0.1.5",
+        "fromManifestSha256": "99220323b89b7412d4eda6b9a169965627744d0f32da9d3a30b8155b49799785",
+        "toVersion": "0.1.6",
+        "toManifestSha256": "7778a8e8cef0b426293c0f73c690a1cd464a0a10d8b9154e558e48ff0b2dbb25"
+      },
+      {
+        "id": "skill.w2-1-digital-human",
+        "fromVersion": "0.1.4",
+        "fromManifestSha256": "280038085869beb851f85189c66f3785b78436cb356f3d4e998f3a7f29f84c06",
+        "toVersion": "0.1.5",
+        "toManifestSha256": "5ed03ba9ea025f8327daae1bf4b56b6b36496eb6ae32bc09b9fe708b7d4bd1db"
+      },
+      {
+        "id": "skill.w2-1-image-digital-human",
+        "fromVersion": "0.1.6",
+        "fromManifestSha256": "12a470f19dd1115cd07b4ea65f7bfe03f2b4a7b1288f2535628a673bcb4a86b7",
+        "toVersion": "0.1.7",
+        "toManifestSha256": "80bbb639b345fd0dd91fba08243755f15bc9d186873cd33bde176603314e2e48"
+      },
+      {
+        "id": "skill.w3-multimodal-video",
+        "fromVersion": "1.2.9",
+        "fromManifestSha256": "393a95738fb1f8eda4bcf048afc695663c00f2d844cce76adb25c22db2eb2c47",
+        "toVersion": "1.2.10",
+        "toManifestSha256": "63aa79081179d5032a6b3dee796fc3c9e137b4edada312029d63ec1d52ff3514"
+      },
+      {
+        "id": "skill.w3-video-copy",
+        "fromVersion": "0.1.36",
+        "fromManifestSha256": "bbb3b9869b3a50b4724c30465e9b4addd7dde1514b4e4814e8d91664d01f64e8",
+        "toVersion": "0.1.37",
+        "toManifestSha256": "1a5c06a3dc14f612d2423b47701fb88f492ee2046741126b03d310c33907fb8a"
+      },
+      {
+        "id": "skill.w3g-video-generation",
+        "fromVersion": "0.1.2",
+        "fromManifestSha256": "d75ecfb49ba264601b360bcec6bc9e5ab19f6e9294ae01b9957da2fd8f41950b",
+        "toVersion": "0.1.3",
+        "toManifestSha256": "08ced5591a854739a7bd6594969d5bcf4ce6d392cf7423e72ac81dceffcb2489"
+      }
+    ]
+  },
+  "signature": {
+    "algorithm": "ed25519",
+    "keyId": "ngg-signing-skill-release-1",
+    "scope": "nggaigc-start-compatibility/v1",
+    "value": "TieQh/DsCu0K6ViZsYATqXFnBIFtnJxk97Nd3j9Jp8F4VfeacC7IE2vOlG5VLz/gWvxXqALy6J9OOiBJi45PDQ=="
+  }
+}