@yijiancaotang/cli 1.0.0 → 1.2.0

package/dist/handoff-wire.js

@@ -0,0 +1,42 @@
+import { verifiedHabit } from "./habit-wire.js";
+import { validDate } from "./query-validation.js";
+const MAX_HANDOFF_BYTES = 64 * 1024;
+const deferredSections = [
+    "project_overview", "project_next_steps", "knowledge_index",
+    "recent_connections", "conditional_reminders", "project_selection"
+];
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+function utcTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?Z$/.exec(value);
+    return !!match && validDate(match[1])
+        && Number(match[2]) <= 23 && Number(match[3]) <= 59 && Number(match[4]) <= 59;
+}
+export function verifiedHandoff(value) {
+    try {
+        if (Buffer.byteLength(JSON.stringify(value) ?? "", "utf8") > MAX_HANDOFF_BYTES)
+            return;
+        const body = record(value);
+        if (!body || body.schema_version !== 1 || body.mode !== "handoff"
+            || body.coverage !== "existing_habit_sections" || !utcTimestamp(body.as_of))
+            return;
+        const deferred = body.deferred_sections;
+        if (!Array.isArray(deferred) || deferred.length !== deferredSections.length
+            || new Set(deferred).size !== deferredSections.length
+            || deferred.some(section => !deferredSections.includes(section)))
+            return;
+        const context = verifiedHabit(body.context, true);
+        if (!context || typeof context.owner_id !== "string" || !Array.isArray(context.missing_sections)
+            || context.missing_sections.some(gap => record(gap)?.section === "calendar_start" || record(gap)?.reason === "record_failed"))
+            return;
+        return {
+            schema_version: 1, mode: "handoff", as_of: body.as_of,
+            coverage: "existing_habit_sections", context,
+            deferred_sections: [...deferredSections]
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/http.js

@@ -3,6 +3,8 @@ import { isPagedQueryPath, isQueryParameterError, isProjectIDParameterError } fr
 import { isSearchParameterError } from "./query-search.js";
 import { isDailyParameterError } from "./query-daily.js";
 import { isCreatePath } from "./create-bundle.js";
+import { isScheduleHeaderPath, scheduleHeaders } from "./schedule-contract.js";
+import { isCalendarHeaderPath, calendarHeaders } from "./calendar-contract.js";
 const maxJSONBytes = 4 * 1024 * 1024;
 const invalidResponse = () => new CliError("invalid_response", "一间草堂返回了无法确认的响应。", "请先核对网页中的实际结果，不要自动重复写入。", 7);
 const invalidRequest = () => new CliError("invalid_request", "请求参数无效。", "请检查命令帮助和输入数据。");
@@ -100,7 +102,15 @@ export class ApiClient {
         }
         if (options.body && typeof options.body === "object" && "device_code" in options.body && typeof options.body.device_code === "string")
             this.secrets.add(options.body.device_code);
-        if (options.headers !== undefined) {
+        if (isScheduleHeaderPath(url.pathname, method)) {
+            for (const [name, value] of Object.entries(scheduleHeaders(url.pathname, method, options.headers)))
+                headers.set(name, value);
+        }
+        else if (isCalendarHeaderPath(url.pathname, method)) {
+            for (const [name, value] of Object.entries(calendarHeaders(url.pathname, method, options.headers)))
+                headers.set(name, value);
+        }
+        else if (options.headers !== undefined) {
             if (!options.headers || Object.keys(options.headers).some((key) => key !== "Idempotency-Key"))
                 throw invalidRequest();
             const key = options.headers["Idempotency-Key"];

package/dist/input-validation.js

@@ -1,3 +1,4 @@
+import { validWorkContextProjectID } from "./work-context-wire.js";
 import { asRecord, CliError } from "./errors.js";
 import { commandHelp } from "./command-help.js";
 export const trimGoSpace = (value) => value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "");
@@ -63,8 +64,21 @@ export function validateCommandArguments(command, flags) {
         return;
     if (Object.entries(flags).some(([key, value]) => value !== undefined && !help.options.includes(`--${key}`)))
         throw flagError(command);
+    if (help.command === "context" && flags.handoff === true && Object.keys(flags).some(key => key !== "handoff" && key !== "project" && flags[key] !== undefined))
+        throw flagError(command);
+    if (help.command === "context" && flags.project !== undefined && (flags.handoff !== true || !validWorkContextProjectID(flags.project)))
+        throw invalidInput(command, { invalid: ["--project"] });
     if (help.command === "context" && flags.start === true && Object.keys(flags).some(key => key !== "start" && flags[key] !== undefined))
         throw flagError(command);
+    if (["project bind", "project binding", "project unbind"].includes(help.command)) {
+        if (flags.confirm !== undefined && (typeof flags.confirm !== "string" || !/^[a-f0-9]{64}$/.test(flags.confirm)))
+            throw invalidInput(command, { invalid: ["--confirm"] });
+        for (const flag of ["local-workspace", "include-subdirs"])
+            if (flags[flag] !== undefined && flags[flag] !== true)
+                throw flagError(command);
+        if (help.command === "project bind" && command.length >= 3 && !validWorkContextProjectID(command[2]))
+            throw invalidInput(command, { invalid: ["<id>"] });
+    }
     const count = (help.usage.match(/<[^>]+>/g) ?? []).length;
     const words = help.command.split(" ").length;
     const positionalCount = help.command === "upload" ? 1 : count;

package/dist/installation.js

@@ -1,12 +1,14 @@
-import { constants, lstatSync, fstatSync, openSync, closeSync, readSync, writeFileSync, fsyncSync, fchmodSync, mkdirSync, readdirSync, rmdirSync } from "node:fs";
+import { constants, lstatSync, fstatSync, openSync, closeSync, readSync, writeFileSync, fsyncSync, fchmodSync, ftruncateSync, mkdirSync, readdirSync, rmdirSync } from "node:fs";
 import { access, lstat, stat, realpath, open, readdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { CliError, asRecord } from "./errors.js";
-import { PLATFORM_IDS, isPlatformId, platformSupported } from "./local-types.js";
+import { PLATFORM_IDS, isSkillTargetId, platformSupported } from "./local-types.js";
 import { bindSkillAgent, completeSkillInventory } from "./skill-assets.js";
 import { acquireLocalLock } from "./local-lock.js";
+import { LEGACY_MANAGED_SKILLS } from "./managed-skill-baseline.js";
+import { REVIEWED_MANAGED_BUNDLE_1_1_0 } from "./reviewed-managed-bundle-baseline.js";
 const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
 const missing = (error) => asRecord(error)?.code === "ENOENT";
 const unsafe = () => new CliError("installation_unsafe", "本地安装位置未通过安全检查。", "请人工检查属主、权限、符号链接与目标目录；不要自动删除、覆盖或修改凭据。");
@@ -128,8 +130,8 @@ export class OwnedTree {
         if (!info.isFile() || info.uid !== this.uid || info.nlink !== 1 || (info.mode & 0o022) !== 0 || info.size > max)
             throw unsafe();
     }
-    readFile(name, max, executable = false) {
-        const check = (info) => { this.checkFile(info, max); if (executable && (info.mode & 0o100) === 0)
+    readFile(name, max, executable = false, mode) {
+        const check = (info) => { this.checkFile(info, max); if (executable && (info.mode & 0o100) === 0 || mode !== undefined && (info.mode & 0o7777) !== mode)
             throw unsafe(); };
         let before;
         try {
@@ -158,9 +160,9 @@ export class OwnedTree {
             closeSync(fd);
         }
     }
-    async read(path, max = 1048576) {
+    async read(path, max = 1048576, mode) {
         return this.directory(dirname(path), false, async (directories) => {
-            return pinned(directories.at(-1), () => this.readFile(basename(path), max));
+            return pinned(directories.at(-1), () => this.readFile(basename(path), max, false, mode));
         });
     }
     async list(path) {
@@ -237,6 +239,43 @@ export class OwnedTree {
         });
         return result === true;
     }
+    // Never truncate on open. Only an exact, single-link managed inode may change;
+    // the caller durably preserves its public before/after bytes before calling.
+    async replaceManaged(entry, rollback = false) {
+        const result = await this.directory(dirname(entry.path), false, async (directories) => pinned(directories.at(-1), () => {
+            const name = basename(entry.path), before = lstatSync(name);
+            const check = (info) => { this.checkFile(info, 1048576); if ((info.mode & 0o7777) !== entry.mode)
+                throw unsafe(); };
+            check(before);
+            const fd = openSync(name, constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const opened = fstatSync(fd);
+                check(opened);
+                if (!unchanged(before, opened) || rollback && (!entry.identity || !same(entry.identity, opened)))
+                    throw unsafe();
+                const expected = rollback ? entry.after : entry.before, next = rollback ? entry.before : entry.after;
+                if (!readDescriptor(fd, 1048576).equals(expected) || !unchanged(opened, fstatSync(fd)) || !unchanged(opened, lstatSync(name)))
+                    throw unsafe();
+                if (!rollback)
+                    entry.identity = opened;
+                writeFileSync(fd, next);
+                ftruncateSync(fd, next.length);
+                fsyncSync(fd);
+                const written = fstatSync(fd), named = lstatSync(name);
+                check(written);
+                check(named);
+                if (!same(opened, written) || !unchanged(written, named) || written.size !== next.length || !readDescriptor(fd, 1048576).equals(next)
+                    || !unchanged(written, fstatSync(fd)) || !unchanged(written, lstatSync(name)))
+                    throw unsafe();
+                return true;
+            }
+            finally {
+                closeSync(fd);
+            }
+        }));
+        if (result !== true)
+            throw unsafe();
+    }
     async removeDirectory(path, expected) {
         await this.directory(dirname(path), false, async (directories) => {
             pinned(directories.at(-1), () => {
@@ -281,6 +320,9 @@ async function readSource(path, max = 1048576) {
         throw sourceInvalid();
     }
 }
+function managedShim(directory) {
+    return Buffer.from(`#!/usr/bin/env node\n// caotang managed command v1\nimport(${JSON.stringify(pathToFileURL(join(directory, "bin", "caotang.cjs")).href)}).catch(()=>{process.stderr.write(JSON.stringify({code:"cli_unavailable",message:"本地命令行暂不可用。",next_action:"请人工核对本地安装，不要重复业务写入。"})+"\\n");process.exitCode=7;});\n`);
+}
 async function bundle(ctx, tree) {
     if (!completeSkillInventory(ctx.assets.map(asset => asset.name)) || ctx.assets.some(asset => hash(asset.content) !== asset.sha256 || !asset.content || Buffer.byteLength(asset.content) > 65536))
         throw sourceInvalid();
@@ -296,16 +338,35 @@ async function bundle(ctx, tree) {
     if (!(await lstat(dist)).isDirectory() || await realpath(dist) !== dist)
         throw sourceInvalid();
     const modules = (await readdir(dist)).filter(name => name.endsWith(".js")).sort();
-    // The shipped runtime has one nested generated dependency. Keep the 64-file
-    // JS limit across both categories; do not recursively trust dist subtrees.
-    if (!modules.includes("cli.js") || modules.length + 1 > 64)
+    // Only reviewed generated dependencies may enter a stable runtime bundle.
+    // Old fixtures/releases with no operations import retain the original closure.
+    if (!modules.includes("cli.js"))
         throw sourceInvalid();
     for (const name of modules) {
         if (!/^[a-z][a-z0-9-]*\.js$/.test(name))
             throw sourceInvalid();
         files.push({ path: `dist/${name}`, bytes: await readSource(join(dist, name)), mode: 0o600 });
     }
-    files.push({ path: "dist/generated/knowledge-growth.js", bytes: await readSource(join(dist, "generated", "knowledge-growth.js")), mode: 0o600 });
+    const generatedModules = ["knowledge-growth.js"];
+    const operationsPath = join(dist, "generated", "agent-operations.js");
+    let hasOperations = false;
+    try {
+        await lstat(operationsPath);
+        hasOperations = true;
+    }
+    catch (error) {
+        if (!missing(error))
+            throw sourceInvalid();
+    }
+    const requiresOperations = files.some(file => file.path.startsWith("dist/") && file.bytes.toString("utf8").includes("generated/agent-operations.js"));
+    if (requiresOperations && !hasOperations)
+        throw sourceInvalid();
+    if (hasOperations)
+        generatedModules.push("agent-operations.js");
+    if (modules.length + generatedModules.length > 64)
+        throw sourceInvalid();
+    for (const name of generatedModules)
+        files.push({ path: `dist/generated/${name}`, bytes: await readSource(join(dist, "generated", name)), mode: 0o600 });
     files.push({ path: "skills/manifest.json", bytes: Buffer.from(JSON.stringify({ formatVersion: 1, skills: ctx.assets.map(({ name, description }) => ({ name, description })) })), mode: 0o600 });
     for (const asset of ctx.assets)
         files.push({ path: `skills/${asset.name}/SKILL.md`, bytes: Buffer.from(asset.content), mode: 0o600 });
@@ -316,14 +377,14 @@ async function bundle(ctx, tree) {
     for (const file of files)
         digest.update(`${file.path}\0${file.mode}\0${file.bytes.length}\0`).update(file.bytes);
     const sha = digest.digest("hex"), directory = join(tree.home, ".caotang", "cli", "releases", sha), command = join(tree.home, ".local", "bin", "caotang");
-    const shim = Buffer.from(`#!/usr/bin/env node\n// caotang managed command v1\nimport(${JSON.stringify(pathToFileURL(join(directory, "bin", "caotang.cjs")).href)}).catch(()=>{process.stderr.write(JSON.stringify({code:"cli_unavailable",message:"本地命令行暂不可用。",next_action:"请人工核对本地安装，不要重复业务写入。"})+"\\n");process.exitCode=7;});\n`);
+    const shim = managedShim(directory);
     return { files, sha, directory, command, shim, version: info.version };
 }
 function validateTargets(ctx, tree) {
-    if (ctx.targets.length > PLATFORM_IDS.length || new Set(ctx.targets.map(target => target.id)).size !== ctx.targets.length)
+    if (ctx.targets.length > PLATFORM_IDS.length + 1 || new Set(ctx.targets.map(target => target.id)).size !== ctx.targets.length)
         throw unsafe();
     for (const target of ctx.targets) {
-        if (!isPlatformId(target.id) || !platformSupported(target.id, ctx.operatingSystem) || !isAbsolute(target.skillDirectory) || tree.within(target.skillDirectory) === tree.home)
+        if (!isSkillTargetId(target.id) || target.id !== "generic" && !platformSupported(target.id, ctx.operatingSystem) || !isAbsolute(target.skillDirectory) || tree.within(target.skillDirectory) === tree.home)
             throw unsafe();
     }
 }
@@ -378,25 +439,160 @@ async function onPath(command, env) {
     }
     return false;
 }
+// The fixed 1.1.0 baseline is admitted only after its complete public runtime
+// inventory verifies. Never infer provenance from a version or receipt.
+async function reviewedV110Bundle(tree, value) {
+    const pin = REVIEWED_MANAGED_BUNDLE_1_1_0, directory = join(tree.home, ".caotang", "cli", "releases", pin.sha);
+    const children = new Map([["", new Set()]]);
+    for (const file of pin.files) {
+        const parts = file.path.split("/");
+        let parent = "";
+        for (const [index, part] of parts.entries()) {
+            children.get(parent).add(part);
+            if (index < parts.length - 1) {
+                parent = parent ? `${parent}/${part}` : part;
+                if (!children.has(parent))
+                    children.set(parent, new Set());
+            }
+        }
+    }
+    const verifyInventory = async () => {
+        for (const [path, expected] of children)
+            if ((await tree.list(join(directory, path)))?.join(",") !== [...expected].sort().join(","))
+                throw conflict();
+    };
+    await verifyInventory();
+    const files = [], digest = createHash("sha256");
+    for (const file of pin.files) {
+        const bytes = await tree.read(join(directory, file.path), file.bytes, file.mode);
+        if (!bytes || bytes.length !== file.bytes || hash(bytes) !== file.sha256)
+            throw conflict();
+        files.push({ path: file.path, bytes, mode: file.mode });
+        digest.update(`${file.path}\0${file.mode}\0${bytes.length}\0`).update(bytes);
+    }
+    if (digest.digest("hex") !== pin.sha)
+        throw conflict();
+    await verifyInventory();
+    const manifest = JSON.parse(files.find(file => file.path === "skills/manifest.json").bytes.toString("utf8"));
+    if (!completeSkillInventory(manifest.skills.map(item => item.name)))
+        throw conflict();
+    const assets = manifest.skills.map(item => { const bytes = files.find(file => file.path === `skills/${item.name}/SKILL.md`).bytes; return { ...item, content: bytes.toString("utf8"), sha256: hash(bytes) }; });
+    return { bundle: { files, sha: pin.sha, version: pin.version, directory, command: value.command, shim: managedShim(directory) }, assets };
+}
+// Keep the reviewed 1.0.0 six-skill baseline unchanged. A directory digest alone
+// cannot authorize replacing somebody's same-name skill.
+async function legacyBundles(ctx, tree, value) {
+    if (!["1.0.1", "1.1.0", "1.1.1", "1.2.0"].includes(value.version) || ctx.agentName === undefined)
+        return [];
+    const releases = join(tree.home, ".caotang", "cli", "releases"), entries = await tree.list(releases) ?? [];
+    if (entries.length > 128)
+        throw unsafe();
+    const found = [];
+    const runtime = Buffer.from(JSON.stringify({ name: "@yijiancaotang/cli", version: "1.0.0", private: true, type: "module", engines: { node: ">=20" }, bin: { caotang: "bin/caotang.cjs" } }));
+    const manifest = Buffer.from(JSON.stringify({ formatVersion: 1, skills: LEGACY_MANAGED_SKILLS.map(({ name, description }) => ({ name, description })) }));
+    for (const sha of entries) {
+        if (!/^[a-f0-9]{64}$/.test(sha) || sha === value.sha)
+            continue;
+        const directory = join(releases, sha), packageBytes = await tree.read(join(directory, "package.json"), 32768, 0o600);
+        if (!packageBytes?.equals(runtime))
+            continue;
+        const root = await tree.list(directory), bin = await tree.list(join(directory, "bin")), dist = await tree.list(join(directory, "dist"));
+        const skills = await tree.list(join(directory, "skills")), generated = await tree.list(join(directory, "dist/generated"));
+        if (root?.join(",") !== "bin,dist,package.json,skills" || bin?.join(",") !== "caotang.cjs" || generated?.join(",") !== "knowledge-growth.js"
+            || !dist || dist.length > 64 || !dist.includes("cli.js") || !dist.includes("generated") || dist.some(name => name !== "generated" && !/^[a-z][a-z0-9-]*\.js$/.test(name))
+            || skills?.join(",") !== [...LEGACY_MANAGED_SKILLS.map(item => item.name), "manifest.json"].sort().join(","))
+            throw conflict();
+        if (!(await tree.read(join(directory, "skills/manifest.json"), 16384, 0o600))?.equals(manifest))
+            throw conflict();
+        const files = [{ path: "package.json", bytes: runtime, mode: 0o600 }, { path: "skills/manifest.json", bytes: manifest, mode: 0o600 }];
+        const assets = [];
+        for (const item of LEGACY_MANAGED_SKILLS) {
+            if ((await tree.list(join(directory, "skills", item.name)))?.join(",") !== "SKILL.md")
+                throw conflict();
+            const bytes = await tree.read(join(directory, "skills", item.name, "SKILL.md"), 65536, 0o600);
+            if (!bytes || hash(bytes) !== item.sha256)
+                throw conflict();
+            assets.push({ ...item, content: bytes.toString("utf8") });
+            files.push({ path: `skills/${item.name}/SKILL.md`, bytes, mode: 0o600 });
+        }
+        for (const path of ["bin/caotang.cjs", ...dist.filter(name => name !== "generated").map(name => `dist/${name}`), "dist/generated/knowledge-growth.js"]) {
+            const mode = path === "bin/caotang.cjs" ? 0o700 : 0o600, bytes = await tree.read(join(directory, path), 1048576, mode);
+            if (!bytes?.length)
+                throw conflict();
+            files.push({ path, bytes, mode });
+        }
+        files.sort((a, b) => a.path.localeCompare(b.path));
+        if (files.reduce((total, file) => total + file.bytes.length, 0) > 5242880)
+            throw conflict();
+        const digest = createHash("sha256");
+        for (const file of files)
+            digest.update(`${file.path}\0${file.mode}\0${file.bytes.length}\0`).update(file.bytes);
+        if (digest.digest("hex") !== sha)
+            throw conflict();
+        found.push({ bundle: { files, sha, version: "1.0.0", directory, command: value.command, shim: managedShim(directory) }, assets });
+    }
+    if (["1.1.0", "1.1.1", "1.2.0"].includes(value.version) && value.sha !== REVIEWED_MANAGED_BUNDLE_1_1_0.sha && entries.includes(REVIEWED_MANAGED_BUNDLE_1_1_0.sha))
+        found.push(await reviewedV110Bundle(tree, value));
+    return found;
+}
+async function installPlan(ctx, tree, value) {
+    const missing = [], modified = [];
+    const newlyInstalledPlatforms = [], upgradedPlatforms = [], replacements = [];
+    for (const target of ctx.targets) {
+        let absent = 0;
+        for (const raw of ctx.assets) {
+            const asset = bindSkillAgent(raw, ctx.agentName), dir = join(target.skillDirectory, asset.name), entries = await tree.list(dir);
+            if (entries === null || entries.length === 0) {
+                missing.push({ target, asset });
+                absent++;
+                continue;
+            }
+            if (entries.length !== 1 || entries[0] !== "SKILL.md")
+                throw skillConflict();
+            const bytes = await tree.read(join(dir, "SKILL.md"), 65536);
+            if (!bytes)
+                throw skillConflict();
+            if (!bytes.equals(Buffer.from(asset.content)))
+                modified.push({ target, asset, bytes });
+        }
+        if (absent === ctx.assets.length)
+            newlyInstalledPlatforms.push(target.id);
+    }
+    const command = await tree.read(value.command);
+    if (command && ((await lstat(value.command)).mode & 0o100) === 0)
+        throw unsafe();
+    const legacy = modified.length || command && !command.equals(value.shim) ? await legacyBundles(ctx, tree, value) : [];
+    for (const item of modified) {
+        const known = legacy.some(source => source.assets.some(asset => asset.name === item.asset.name && Buffer.from(bindSkillAgent(asset, ctx.agentName).content).equals(item.bytes)));
+        if (!known)
+            throw skillConflict();
+        const path = join(item.target.skillDirectory, item.asset.name, "SKILL.md");
+        if (!(await tree.read(path, 65536, 0o600))?.equals(item.bytes))
+            throw unsafe();
+        replacements.push({ path, before: item.bytes, after: Buffer.from(item.asset.content), mode: 0o600, label: `${item.target.id}:${item.asset.name}` });
+        if (!upgradedPlatforms.includes(item.target.id))
+            upgradedPlatforms.push(item.target.id);
+    }
+    if (command && !command.equals(value.shim)) {
+        if (!legacy.some(source => source.bundle.shim.equals(command)))
+            throw conflict();
+        if (!(await tree.read(value.command, 1048576, 0o700))?.equals(command))
+            throw unsafe();
+        // Always switch the shared stable command after every selected skill succeeds.
+        replacements.push({ path: value.command, before: command, after: value.shim, mode: 0o700, label: "command" });
+    }
+    return { missing, replacements, newlyInstalledPlatforms, upgradedPlatforms };
+}
 export async function installLocal(ctx) {
     const tree = new OwnedTree(ctx.homeDir), changed = [];
     let changesPossible = false;
-    const newlyInstalledPlatforms = [];
     try {
         validateTargets(ctx, tree);
         if (!ctx.targets.length && !ctx.agentName)
             throw new CliError("no_supported_platform", "未识别到支持的AI客户端。", "核对Claude Code、Codex、OpenClaw，或macOS上的Kimi Code、Kimi工作模式、WorkBuddy后再接入；不会自动安装客户端。");
         const value = await bundle(ctx, tree);
         await tree.directory(tree.home, false, async () => { });
-        for (const target of ctx.targets)
-            for (const asset of ctx.assets)
-                if (await skillState(tree, target, bindSkillAgent(asset, ctx.agentName)) === "modified")
-                    throw skillConflict();
-        const existingCommand = await tree.read(value.command);
-        if (existingCommand && !existingCommand.equals(value.shim))
-            throw conflict();
-        if (existingCommand && ((await lstat(value.command)).mode & 0o100) === 0)
-            throw unsafe();
+        await installPlan(ctx, tree, value);
         if (await bundleState(tree, value) === "modified")
             throw conflict();
         const lockPath = join(tree.home, ".caotang", ".setup.lock");
@@ -411,13 +607,7 @@ export async function installLocal(ctx) {
             const state = await bundleState(tree, value);
             if (state === "modified")
                 throw conflict();
-            for (const target of ctx.targets) {
-                const statuses = await Promise.all(ctx.assets.map(asset => skillState(tree, target, bindSkillAgent(asset, ctx.agentName))));
-                if (statuses.includes("modified"))
-                    throw skillConflict();
-                if (statuses.every(status => status === "missing"))
-                    newlyInstalledPlatforms.push(target.id);
-            }
+            const originalPlan = await installPlan(ctx, tree, value);
             if (state === "missing") {
                 const created = await tree.createDirectory(value.directory);
                 if (!created)
@@ -428,25 +618,79 @@ export async function installLocal(ctx) {
                 if (await bundleState(tree, value) !== "installed")
                     throw conflict();
             }
-            for (const target of ctx.targets)
-                for (const asset of ctx.assets) {
-                    if (await skillState(tree, target, bindSkillAgent(asset, ctx.agentName)) === "installed")
-                        continue;
-                    const dir = join(target.skillDirectory, asset.name), created = await tree.createDirectory(dir);
-                    if (!created && (await tree.list(dir))?.length !== 0)
-                        throw skillConflict();
-                    changed.push(`${target.id}:${asset.name}`);
-                    await tree.writeNew(join(dir, "SKILL.md"), Buffer.from(bindSkillAgent(asset, ctx.agentName).content), 0o600);
-                    if (await skillState(tree, target, bindSkillAgent(asset, ctx.agentName)) !== "installed")
-                        throw skillConflict();
+            for (const { target, asset } of originalPlan.missing) {
+                const dir = join(target.skillDirectory, asset.name), created = await tree.createDirectory(dir);
+                if (!created && (await tree.list(dir))?.length !== 0)
+                    throw skillConflict();
+                changed.push(`${target.id}:${asset.name}`);
+                await tree.writeNew(join(dir, "SKILL.md"), Buffer.from(asset.content), 0o600);
+                if (await skillState(tree, target, asset) !== "installed")
+                    throw skillConflict();
+            }
+            const plan = await installPlan(ctx, tree, value), attempted = [];
+            let recoveryJournal;
+            if (plan.replacements.length) {
+                const snapshot = Buffer.from(JSON.stringify({ formatVersion: 1, targetBundleSha: value.sha, files: plan.replacements.map(entry => ({ path: relative(tree.home, entry.path), mode: entry.mode, before: entry.before.toString("base64"), after: entry.after.toString("base64") })) }));
+                if (snapshot.length > 1048576)
+                    throw unsafe();
+                recoveryJournal = join(tree.home, ".caotang", "cli", "upgrades", hash(snapshot) + ".json");
+                await tree.writeNew(recoveryJournal, snapshot, 0o600);
+                if (!(await tree.read(recoveryJournal, 1048576, 0o600))?.equals(snapshot))
+                    throw unsafe();
+                await tree.directory(dirname(recoveryJournal), false, async (directories) => {
+                    for (const directory of directories)
+                        await directory.handle.sync();
+                });
+            }
+            try {
+                for (const entry of plan.replacements) {
+                    attempted.push(entry);
+                    changed.push(entry.label);
+                    await tree.replaceManaged(entry);
+                }
+                if (await tree.writeNew(value.command, value.shim, 0o700))
+                    changed.push("command");
+                if (!(await tree.read(value.command))?.equals(value.shim) || ((await lstat(value.command)).mode & 0o100) === 0 || await bundleState(tree, value) !== "installed")
+                    throw conflict();
+                for (const target of ctx.targets)
+                    for (const asset of ctx.assets)
+                        if (await skillState(tree, target, bindSkillAgent(asset, ctx.agentName)) !== "installed")
+                            throw skillConflict();
+            }
+            catch (error) {
+                if (!recoveryJournal)
+                    throw error;
+                let restored = true;
+                for (const entry of attempted.reverse()) {
+                    try {
+                        const current = await tree.read(entry.path, 1048576, entry.mode);
+                        if (!current?.equals(entry.before)) {
+                            if (!entry.identity) {
+                                restored = false;
+                                continue;
+                            }
+                            await tree.replaceManaged(entry, true);
+                        }
+                        if (!(await tree.read(entry.path, 1048576, entry.mode))?.equals(entry.before)
+                            || entry.identity && !same(await lstat(entry.path), entry.identity))
+                            restored = false;
+                    }
+                    catch {
+                        restored = false;
+                    }
                 }
-            if (await tree.writeNew(value.command, value.shim, 0o700))
-                changed.push("command");
+                const recovery = { upgrade_status: restored ? "rolled_back" : "unknown", recovery_journal: recoveryJournal };
+                if (restored && error instanceof CliError && error.code === "installation_permission_denied") {
+                    Object.assign(error.details, recovery);
+                    throw error;
+                }
+                throw new CliError(restored ? "installation_upgrade_failed" : "installation_upgrade_unknown", restored ? "本地升级未完成，已核对并恢复本轮改动的原文件。" : "无法确认本地升级结果，部分受管文件可能尚未恢复。", "保留旧版本与恢复原件，请本人核对 recovery_journal；不要强制覆盖、删除、重新授权或重复业务写入。", 7, recovery);
+            }
+            return { changed, bundleSha: value.sha, bundleDirectory: value.directory, newlyInstalledPlatforms: originalPlan.newlyInstalledPlatforms, upgradedPlatforms: originalPlan.upgradedPlatforms };
         }
         finally {
             release();
         }
-        return { changed, bundleSha: value.sha, bundleDirectory: value.directory, newlyInstalledPlatforms };
     }
     catch (error) {
         const safe = error instanceof CliError ? error
@@ -483,9 +727,54 @@ export async function inspectLocalInstallation(ctx) {
             }
             skills.push({ name: asset.name, status });
             if (target.detected && status !== "installed")
-                issue(status === "missing" ? "skill_missing" : status === "modified" ? "skill_modified" : "skill_unsafe", "本地技能缺失、已修改或不满足安全要求。", status === "missing" ? `运行 setup --platform ${target.id} 安装缺失技能。` : "保留现有技能并人工核对，不自动覆盖或修复。");
+                issue(status === "missing" ? "skill_missing" : status === "modified" ? "skill_modified" : "skill_unsafe", "本地技能缺失、已修改或不满足安全要求。", status === "missing" ? (target.id === "generic" ? "保留本次 --skills-dir 的明确目录再运行 setup；不会猜测其他技能位置。" : `运行 setup --platform ${target.id} 安装缺失技能。`) : "保留现有技能并人工核对，不自动覆盖或修复。");
         }
         platforms.push({ id: target.id, detected: target.detected, skill_directory: target.skillDirectory, skills });
     }
     return { command: { installed, on_path, version: value.version, ...(installed ? { executable_path: value.command } : {}) }, platforms, issues };
 }
+// Read-only evidence for known platform paths, never an installation/overwrite
+// permit. Only the current name's exact public templates count as its skills.
+export async function inspectManagedOrigins(ctx) {
+    if (ctx.agentName === undefined)
+        throw new CliError("agent_name_required", "请用你自己的名字再运行 setup --agent <你的名字>。", "之后每条命令都带同一个 --agent <你的名字>；不会借用其他 AI 的连接。");
+    const tree = new OwnedTree(ctx.homeDir);
+    validateTargets(ctx, tree);
+    const value = await bundle(ctx, tree), assets = ctx.assets.map(asset => bindSkillAgent(asset, ctx.agentName));
+    let legacy = [];
+    try {
+        legacy = await legacyBundles(ctx, tree, value);
+    }
+    catch { /* Unverified old files provide no evidence; never promote them. */ }
+    const platforms = [];
+    for (const target of ctx.targets) {
+        const skills = [];
+        for (const asset of assets) {
+            let status;
+            try {
+                status = await skillState(tree, target, asset);
+                if (status === "modified") {
+                    const dir = join(target.skillDirectory, asset.name), entries = await tree.list(dir);
+                    if (entries?.join(",") === "SKILL.md") {
+                        const bytes = await tree.read(join(dir, "SKILL.md"), 65536, 0o600);
+                        if (bytes && legacy.some(source => source.assets.some(old => old.name === asset.name && Buffer.from(bindSkillAgent(old, ctx.agentName).content).equals(bytes))))
+                            status = "outdated";
+                    }
+                }
+            }
+            catch {
+                status = "unsafe";
+            }
+            skills.push({ name: asset.name, status });
+        }
+        platforms.push({ id: target.id, skill_directory: target.skillDirectory, ownKnownCount: skills.filter(skill => skill.status === "installed" || skill.status === "outdated").length, skills });
+    }
+    let command = { legacyManaged: false, on_path: false };
+    try {
+        const bytes = await tree.read(value.command, 1048576, 0o700), old = legacy.find(source => bytes?.equals(source.bundle.shim));
+        if (old)
+            command = { legacyManaged: true, on_path: await onPath(value.command, ctx.env), version: old.bundle.version, executable_path: value.command };
+    }
+    catch { /* An unsafe command must not be called a verified old command. */ }
+    return { platforms, command };
+}