@nowcrew/daemon 0.6.77-beta.9 → 0.6.78

package/dist/project-skills/reconciler.js

@@ -1,552 +1,166 @@
-import { cp, lstat, mkdir, readdir, readlink, stat, symlink, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { dirname, join, posix, win32 } from "node:path";
-import { isManagedDirectoryProjectionCopy, projectDirectory, } from "../directory-projection.js";
-import { runtimeProjectionLifetime, } from "./agent-projection-coordinator.js";
-import { commitPreparedProjectSkillManifestUpdate, computeProjectSkillBindingDigest, computeProjectSkillResolutionDigest, createAppliedProjectSkillManifest, prepareAppliedProjectSkillManifestRemoval, prepareAppliedProjectSkillManifestUpdate, publishPreparedProjectSkillManifestUpdate, readAppliedProjectSkillManifest, recoverAppliedProjectSkillManifestUpdates, rollbackPreparedProjectSkillManifestUpdate, } from "./projection-state.js";
+/**
+ * Project Skill 解析 + 执行编排。
+ * reconcile: server 同步绑定时只解析"哪些 skill 在本机可用",不碰磁盘。
+ * prepareAndLaunch: 为这一次 execution 建独占投影目录 → 启动 runtime → 进程树确认退出后删除。
+ * 没有共享目录,所以没有锁、租约、manifest、GC。ownership 未确认时目录保留,交给启动 sweep。
+ */
+import { lstat, stat } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { ExecutionProjectionError, materializeExecutionProjection, removeExecutionProjection, } from "./execution-projection.js";
+import { projectSkillResolutionRecords } from "./scanner.js";
 import { compareProjectSkillRefs, } from "./types.js";
-import { PROJECT_SKILL_RUNTIME_MATERIALIZATION_REVISION, ProjectSkillRuntimeStoreError, } from "./runtime-root-domain.js";
-import { createProjectSkillRuntimeRootStore, } from "./runtime-root-store.js";
-import { createProjectSkillRuntimeLeaseStore, } from "./runtime-root-leases.js";
-import { createProjectSkillRuntimeRootGc, } from "./runtime-root-gc.js";
-import { projectSkillProjectionExpectation, projectSkillResolutionRecords, } from "./scanner.js";
-import { cleanupProjectionStaging, isManagedProjectionRoot, markProjectionStaging, PROJECTION_ROOT_MARKER_NAME, projectionTargets, recoverProjectionSwitch, switchProjectionSet, } from "./projection-set-switch.js";
 export class ProjectProjectionError extends Error {
     code;
-    constructor(code) {
-        super(code);
+    reason;
+    constructor(code, reason) {
+        super(reason === undefined ? code : `${code}: ${reason}`);
         this.code = code;
+        this.reason = reason;
         this.name = "ProjectProjectionError";
     }
 }
-/** A process may still own its leased root; only startup/journal recovery may clear this state. */
+/** runtime 进程树停止无法证明时抛出;调用方必须保留投影目录与非终态 journal。 */
 export class ProjectSkillRuntimeOwnershipUnverifiedError extends AggregateError {
     code = "project_skill_runtime_ownership_unverified";
-    constructor() {
+    /** cause 保留触发它的原始错误(例如 exit 的 rejection),否则排查时只剩两条固定的占位错误。 */
+    constructor(cause) {
         super([
             new Error("project_skill_runtime_lifetime_rejected"),
             new Error("project_skill_runtime_stop_unverified"),
-        ], "project_skill_runtime_ownership_unverified");
+        ], "project_skill_runtime_ownership_unverified", cause === undefined ? undefined : { cause });
         this.name = "ProjectSkillRuntimeOwnershipUnverifiedError";
     }
 }
-export const decideProjectSkillProjection = (expected, applied) => {
-    if (applied === null || expected.generation > applied.generation) {
-        return Object.freeze({ kind: "ensure-applied" });
-    }
-    if (expected.generation < applied.generation) {
-        return Object.freeze({ kind: "use-advanced", warning: "skill_projection_advanced" });
-    }
-    if (expected.bindingDigest !== applied.bindingDigest) {
-        return Object.freeze({ kind: "reject", code: "skill_projection_snapshot_corrupt" });
-    }
-    if (applied.rootId === null)
-        return Object.freeze({ kind: "ensure-applied" });
-    return expected.resolutionDigest === applied.resolutionDigest
-        ? Object.freeze({ kind: "use-current" })
-        : Object.freeze({ kind: "ensure-applied" });
-};
-/** Unlike the v1 lock lifetime helper, a rejected v2 exit is not a full-tree stop proof. */
-const verifiedRuntimeProjectionLifetime = (value) => {
-    if (typeof value !== "object" || value === null || !("exit" in value))
-        return Promise.resolve();
-    const exit = value.exit;
-    return exit instanceof Promise ? exit : Promise.resolve();
-};
-const ownershipVerifiedRuntimeProjection = (value) => {
-    if (typeof value !== "object" || value === null || !("exit" in value))
-        return value;
-    const exit = value.exit;
-    if (!(exit instanceof Promise))
-        return value;
-    return {
-        ...value,
-        exit: exit.catch(() => { throw new ProjectSkillRuntimeOwnershipUnverifiedError(); }),
-    };
-};
-const exists = async (path) => lstat(path).then(() => true, () => false);
+const SAFE_HANDLE = /^[A-Za-z0-9._-]{1,128}$/u;
 const canonicalConflictFreeBindings = (bindings) => {
-    const unique = [...new Map(bindings.map((binding) => [
-            `${binding.projectId}\0${binding.skillName}`,
-            binding,
-        ])).values()].sort(compareProjectSkillRefs);
-    const names = new Map();
+    const unique = [...new Map(bindings
+            .map((binding) => [`${binding.projectId}\0${binding.skillName}`, binding])).values()]
+        .sort(compareProjectSkillRefs);
+    const owners = new Map();
     for (const binding of unique) {
-        const owner = names.get(binding.skillName);
+        const owner = owners.get(binding.skillName);
         if (owner !== undefined && owner !== binding.projectId) {
             throw new ProjectProjectionError("skill_name_conflict");
         }
-        names.set(binding.skillName, binding.projectId);
+        owners.set(binding.skillName, binding.projectId);
     }
     return Object.freeze(unique);
 };
-const normalizeWindowsLinkIdentity = (value) => {
-    if (/^\\\\\?\\UNC\\/iu.test(value))
-        return `\\\\${value.slice(8)}`;
-    if (/^\\\\\?\\[A-Za-z]:\\/u.test(value))
-        return value.slice(4);
-    return value;
-};
-const isSameOrWithin = (root, candidate, path) => {
-    const relative = path.relative(root, candidate);
-    return relative === ""
-        || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-};
-export const canonicalTrainingSkillLinkTarget = (source, link, trainingSkillsRoot, platform) => {
-    const path = platform === "win32" ? win32 : posix;
-    const normalizedSource = platform === "win32" ? normalizeWindowsLinkIdentity(source) : source;
-    const normalizedLink = platform === "win32" ? normalizeWindowsLinkIdentity(link) : link;
-    const normalizedTrainingRoot = platform === "win32"
-        ? normalizeWindowsLinkIdentity(trainingSkillsRoot)
-        : trainingSkillsRoot;
-    const resolvedLink = path.resolve(path.dirname(normalizedSource), normalizedLink);
-    return isSameOrWithin(path.normalize(normalizedTrainingRoot), resolvedLink, path)
-        ? path.normalize(resolvedLink)
-        : null;
-};
-export const isTrainingSkillLink = (source, link, trainingSkillsRoot, platform) => canonicalTrainingSkillLinkTarget(source, link, trainingSkillsRoot, platform) !== null;
-const preserveNonProjectSkills = async (projectionTarget, trainingSkillsRoot, platform, projectSkillNames) => {
-    const names = new Set();
-    if (!await exists(projectionTarget.target))
-        return names;
-    const rootInfo = await lstat(projectionTarget.target);
-    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
-        throw new ProjectProjectionError("skill_projection_failed");
+/** 源目录必须是真实目录且有 SKILL.md,否则按 missing 处理(warning,不阻断)。 */
+const actualResolutionRecords = async (bindings, projects, platform) => Object.freeze(await Promise.all(projectSkillResolutionRecords(bindings, projects, platform).map(async (record) => {
+    if (record.mode === "missing" || record.sourcePath === null)
+        return record;
+    const [source, skillFile] = await Promise.all([
+        lstat(record.sourcePath).catch(() => null),
+        stat(join(record.sourcePath, "SKILL.md")).catch(() => null),
+    ]);
+    if (source?.isDirectory() === true && !source.isSymbolicLink() && skillFile?.isFile() === true) {
+        return record;
     }
-    const managedRoot = await isManagedProjectionRoot(projectionTarget.target, projectionTarget);
-    for (const entry of await readdir(projectionTarget.target, { withFileTypes: true })) {
-        if (entry.name === PROJECTION_ROOT_MARKER_NAME) {
-            if (managedRoot)
-                continue;
-            throw new ProjectProjectionError("skill_projection_failed");
-        }
-        const source = join(projectionTarget.target, entry.name);
-        const destination = join(projectionTarget.staging, entry.name);
-        if (platform === "win32" && await isManagedDirectoryProjectionCopy(source, platform))
-            continue;
-        const info = await lstat(source);
-        if (info.isSymbolicLink()) {
-            const link = await readlink(source);
-            const canonicalTarget = canonicalTrainingSkillLinkTarget(source, link, trainingSkillsRoot, platform);
-            if (canonicalTarget === null)
-                continue;
-            if (projectSkillNames.has(entry.name))
-                continue;
-            await symlink(platform === "win32" ? canonicalTarget : link, destination, platform === "win32" ? "junction" : "dir");
-        }
-        else {
-            await cp(source, destination, { recursive: true, preserveTimestamps: true });
-        }
-        names.add(entry.name);
-    }
-    return names;
+    return Object.freeze({
+        projectId: record.projectId,
+        skillName: record.skillName,
+        sourcePath: null,
+        mode: "missing",
+    });
+})));
+const toResolutions = (records) => Object.freeze(records.map((record) => Object.freeze({
+    projectId: record.projectId,
+    skillName: record.skillName,
+    status: record.mode === "resolved" ? "linked" : "unavailable",
+})));
+const exitPromiseOf = (value) => {
+    if (typeof value !== "object" || value === null || !("exit" in value))
+        return null;
+    const exit = value.exit;
+    return exit instanceof Promise ? exit : null;
 };
 export function createProjectSkillsReconciler(deps) {
     const platform = deps.platform ?? process.platform;
-    const directoryProjector = deps.projectDirectory ?? projectDirectory;
-    const readOptions = { platform };
-    const readApplied = deps.readAppliedManifest ?? readAppliedProjectSkillManifest;
-    const prepareRemoval = deps.prepareAppliedManifestRemoval ?? prepareAppliedProjectSkillManifestRemoval;
-    const prepareUpdate = deps.prepareAppliedManifestUpdate ?? prepareAppliedProjectSkillManifestUpdate;
-    const publishUpdate = deps.publishAppliedManifestUpdate
-        ?? ((update) => publishPreparedProjectSkillManifestUpdate(update, readOptions));
-    const commitUpdate = deps.commitAppliedManifestUpdate
-        ?? ((update) => commitPreparedProjectSkillManifestUpdate(update, readOptions));
-    const rollbackUpdate = deps.rollbackAppliedManifestUpdate
-        ?? ((update) => rollbackPreparedProjectSkillManifestUpdate(update, readOptions));
-    const manifestOperations = Object.freeze({
-        publish: publishUpdate,
-        commit: commitUpdate,
-        rollback: rollbackUpdate,
-    });
-    const runtimeRoots = deps.runtimeRoots ?? createProjectSkillRuntimeRootStore({ platform });
-    const runtimeLeases = deps.runtimeLeases ?? createProjectSkillRuntimeLeaseStore({ platform });
-    const runtimeRootGc = deps.runtimeRootGc ?? createProjectSkillRuntimeRootGc({ platform, runtimeRoots });
-    const protectedExecutionIds = deps.protectedExecutionIds ?? new Set();
-    let lastProjectionDiagnostics = Object.freeze([]);
-    const reconcileUnlocked = async (handle, bindings, projects = deps.scannedProjects(), recover = true, manifestPublication) => {
-        const agentRoot = join(deps.agentsRoot, handle);
-        if (recover) {
-            try {
-                await recoverProjectionSwitch(agentRoot, deps.syncDirectory);
-            }
-            catch {
-                throw new ProjectProjectionError("skill_projection_failed");
-            }
-        }
-        const uniqueBindings = canonicalConflictFreeBindings(bindings);
-        const linked = [];
-        const resolutions = [];
-        const resolutionRecords = [];
-        for (const binding of uniqueBindings) {
-            const project = projects.find((candidate) => candidate.inventory.projectId === binding.projectId
-                && candidate.inventory.status === "available");
-            const skill = project?.resolved.find((candidate) => candidate.name === binding.skillName);
-            const available = skill !== undefined && (await stat(skill.sourcePath).catch(() => null))?.isDirectory() === true;
-            resolutions.push(Object.freeze({ ...binding, status: available ? "linked" : "unavailable" }));
-            if (available && skill !== undefined) {
-                linked.push({ binding, skill });
-                resolutionRecords.push(Object.freeze({
-                    ...binding,
-                    sourcePath: skill.sourcePath,
-                    mode: "resolved",
-                }));
-            }
-            else {
-                resolutionRecords.push(Object.freeze({ ...binding, sourcePath: null, mode: "missing" }));
-            }
-        }
-        const linkedNames = new Set(linked.map((item) => item.binding.skillName));
-        const id = randomUUID();
-        const targets = projectionTargets(agentRoot, id);
-        const nextProjectionDiagnostics = [];
-        try {
-            for (const target of targets) {
-                await mkdir(dirname(target.target), { recursive: true });
-                await mkdir(target.staging, { mode: 0o700 });
-                await markProjectionStaging(target, id);
-                const preservedNames = await preserveNonProjectSkills(target, join(agentRoot, "training", "skills"), platform, linkedNames);
-                for (const item of linked) {
-                    if (preservedNames.has(item.binding.skillName)) {
-                        throw new ProjectProjectionError("skill_name_conflict");
-                    }
-                    const projectionTarget = join(target.staging, item.binding.skillName);
-                    const projection = await directoryProjector(item.skill.sourcePath, projectionTarget, platform, { finalTarget: join(target.target, item.binding.skillName) });
-                    nextProjectionDiagnostics.push(Object.freeze({
-                        runtime: target.runtime,
-                        projectId: item.binding.projectId,
-                        skillName: item.binding.skillName,
-                        mode: projection.mode,
-                        ...(projection.copyProtection === undefined
-                            ? {}
-                            : { copyProtection: projection.copyProtection }),
-                    }));
-                }
-            }
-            await writeFile(join(agentRoot, ".nowwork-root"), "", { encoding: "utf8", mode: 0o600 });
-            for (const target of targets)
-                await deps.beforeSwitch?.(target.runtime);
-            const publication = await manifestPublication?.(Object.freeze(resolutionRecords));
-            await switchProjectionSet(agentRoot, targets, id, deps.switchFault, deps.syncDirectory, publication);
-            lastProjectionDiagnostics = Object.freeze(nextProjectionDiagnostics);
-            return Object.freeze({
-                resolutions: Object.freeze(resolutions),
-                resolutionRecords: Object.freeze(resolutionRecords),
-            });
-        }
-        catch (error) {
-            try {
-                await Promise.all(targets.map((target) => cleanupProjectionStaging(target, id, deps.syncDirectory)));
-            }
-            catch {
-                throw new ProjectProjectionError("skill_projection_failed");
-            }
-            if (error instanceof ProjectProjectionError)
-                throw error;
-            throw new ProjectProjectionError("skill_projection_failed");
-        }
-    };
-    const validateExpectation = (expected) => {
-        const canonical = [...expected.bindings].sort(compareProjectSkillRefs);
-        const isCanonical = canonical.length === expected.bindings.length
-            && canonical.every((binding, index) => binding.projectId === expected.bindings[index]?.projectId
-                && binding.skillName === expected.bindings[index]?.skillName)
-            && canonical.every((binding, index) => index === 0
-                || binding.projectId !== canonical[index - 1]?.projectId
-                || binding.skillName !== canonical[index - 1]?.skillName);
-        const digestShape = /^sha256:[a-f0-9]{64}$/u;
-        let bindingDigestMatches = false;
-        try {
-            bindingDigestMatches = computeProjectSkillBindingDigest(expected.bindings) === expected.bindingDigest;
-        }
-        catch {
-            bindingDigestMatches = false;
-        }
-        if (!isCanonical
-            || !Number.isInteger(expected.generation)
-            || expected.generation < 0
-            || expected.generation > 2_147_483_647
-            || !digestShape.test(expected.resolutionDigest)
-            || !bindingDigestMatches) {
-            throw new ProjectProjectionError("skill_projection_snapshot_corrupt");
-        }
-    };
-    const rejectDecision = (decision) => {
-        if (decision.kind === "reject")
-            throw new ProjectProjectionError(decision.code);
-    };
-    const mapRuntimeRootError = (error) => {
-        if (error instanceof ProjectProjectionError)
-            throw error;
-        if (error instanceof ProjectSkillRuntimeStoreError
-            && error.code === "skill_projection_snapshot_corrupt") {
-            throw new ProjectProjectionError("skill_projection_snapshot_corrupt");
+    const agentsRoot = resolve(deps.agentsRoot);
+    const agentRootFor = (handle) => {
+        if (!SAFE_HANDLE.test(handle) || handle === "." || handle === "..") {
+            throw new ProjectProjectionError("skill_projection_failed", "unsafe_handle");
         }
-        throw new ProjectProjectionError("skill_projection_failed");
-    };
-    const exactManifest = (left, right) => left !== null && JSON.stringify(left) === JSON.stringify(right);
-    const warningsFor = (records) => Object.freeze(records
-        .filter((record) => record.mode === "missing")
-        .map((record) => Object.freeze({
-        projectId: record.projectId,
-        skillName: record.skillName,
-        code: "project_skill_unavailable",
-    })));
-    const withWarnings = (decision, warnings) => {
-        if (decision.kind === "reject" || warnings.length === 0) {
-            return decision;
+        const agentRoot = resolve(agentsRoot, handle);
+        if (!agentRoot.startsWith(`${agentsRoot}${sep}`)) {
+            throw new ProjectProjectionError("skill_projection_failed", "unsafe_handle");
         }
-        return Object.freeze({ ...decision, warnings });
+        return agentRoot;
     };
-    const actualResolutionRecords = async (bindings, projects) => Object.freeze(await Promise.all(projectSkillResolutionRecords(bindings, projects, platform).map(async (record) => {
-        if (record.mode === "missing" || record.sourcePath === null)
-            return record;
-        const sourcePath = record.sourcePath;
-        const [source, skillFile] = await Promise.all([
-            lstat(sourcePath).catch(() => null),
-            stat(join(sourcePath, "SKILL.md")).catch(() => null),
-        ]);
-        if (source?.isDirectory() === true
-            && !source.isSymbolicLink()
-            && skillFile?.isFile() === true) {
-            return record;
-        }
-        return Object.freeze({
-            projectId: record.projectId,
-            skillName: record.skillName,
-            sourcePath: null,
-            mode: "missing",
-        });
-    })));
-    const commitAppliedRoot = async (agentRoot, applied) => {
-        const update = await prepareUpdate(agentRoot, applied, readOptions);
-        await publishUpdate(update);
-        await deps.afterManifestPublishedBeforeCommit?.();
-        await commitUpdate(update);
-        if (!exactManifest(await readApplied(agentRoot, readOptions), applied)) {
-            throw new ProjectProjectionError("skill_projection_failed");
-        }
-    };
-    const ensureRuntimeRootLocked = async (handle, requested, options = {}) => {
-        const agentRoot = join(deps.agentsRoot, handle);
+    const cleanup = async (agentRoot, executionId) => {
         try {
-            canonicalConflictFreeBindings(requested.bindings);
-            await recoverProjectionSwitch(agentRoot, deps.syncDirectory, manifestOperations);
-            await recoverAppliedProjectSkillManifestUpdates(agentRoot, readOptions);
-            await runtimeRoots.recover(agentRoot);
-            const projects = deps.scannedProjects();
-            const wireRequest = Object.freeze({
-                bindings: requested.bindings,
-                generation: requested.generation,
-            });
-            let cachedRequested;
-            try {
-                cachedRequested = projectSkillProjectionExpectation(wireRequest, projects, platform);
-            }
-            catch (error) {
-                if (error instanceof ProjectProjectionError)
-                    throw error;
-                throw new ProjectProjectionError("skill_projection_snapshot_corrupt");
-            }
-            const localResolutions = await actualResolutionRecords(cachedRequested.bindings, projects);
-            const localRequested = Object.freeze({
-                ...cachedRequested,
-                resolutionDigest: computeProjectSkillResolutionDigest(localResolutions, platform),
-            });
-            validateExpectation(localRequested);
-            if ("resolutionDigest" in requested)
-                validateExpectation(requested);
-            const current = await readApplied(agentRoot, readOptions);
-            const callerDecision = decideProjectSkillProjection(localRequested, current);
-            rejectDecision(callerDecision);
-            const desiredBindings = callerDecision.kind === "use-advanced" && current !== null
-                ? current.bindings
-                : localRequested.bindings;
-            const desiredGeneration = callerDecision.kind === "use-advanced" && current !== null
-                ? current.generation
-                : localRequested.generation;
-            const resolutions = callerDecision.kind === "use-advanced"
-                ? await actualResolutionRecords(desiredBindings, projects)
-                : localResolutions;
-            const desiredExpectation = Object.freeze({
-                bindings: desiredBindings,
-                generation: desiredGeneration,
-                bindingDigest: computeProjectSkillBindingDigest(desiredBindings),
-                resolutionDigest: computeProjectSkillResolutionDigest(resolutions, platform),
-            });
-            const inventory = await runtimeRoots.list(agentRoot);
-            const currentRecord = current?.rootId === null || current?.rootId === undefined
-                ? undefined
-                : inventory.find((record) => record.rootId === current.rootId);
-            const reusableIdentity = current !== null
-                && current.rootId !== null
-                && current.generation === desiredExpectation.generation
-                && current.bindingDigest === desiredExpectation.bindingDigest
-                && current.resolutionDigest === desiredExpectation.resolutionDigest
-                && currentRecord?.materializationRevision === PROJECT_SKILL_RUNTIME_MATERIALIZATION_REVISION
-                && currentRecord.bindingDigest === current.bindingDigest
-                && currentRecord.resolutionDigest === current.resolutionDigest;
-            let runtimeRoot;
-            let published = false;
-            const reusableRootId = reusableIdentity ? current.rootId : null;
-            const currentInspection = reusableRootId === null
-                ? null
-                : await runtimeRoots.inspect(agentRoot, reusableRootId);
-            const reusable = currentInspection !== null
-                && (!options.refreshCopyProjection || !currentInspection.containsCopyProjection);
-            if (reusable) {
-                runtimeRoot = currentInspection.descriptor;
-            }
-            else {
-                runtimeRoot = await runtimeRoots.publish({
-                    agentRoot,
-                    bindingDigest: desiredExpectation.bindingDigest,
-                    resolutionDigest: desiredExpectation.resolutionDigest,
-                    resolutions,
-                });
-                published = true;
-                await deps.afterRootPublishedBeforeAppliedCommit?.(runtimeRoot);
-                const applied = createAppliedProjectSkillManifest({
-                    bindings: desiredBindings,
-                    generation: desiredGeneration,
-                    resolutions,
-                    rootId: runtimeRoot.rootId,
-                    platform,
-                });
-                await commitAppliedRoot(agentRoot, applied);
-            }
-            const baseDecision = callerDecision.kind === "use-advanced"
-                ? callerDecision
-                : Object.freeze({ kind: published ? "ensure-applied" : "use-current" });
-            return Object.freeze({
-                decision: withWarnings(baseDecision, warningsFor(resolutions)),
-                runtimeRoot,
-            });
+            await removeExecutionProjection(agentRoot, executionId);
         }
         catch (error) {
-            return mapRuntimeRootError(error);
+            deps.onCleanupFailed?.(executionId, error);
         }
     };
-    const ensureApplied = async (handle, expected, options = {}) => {
-        validateExpectation(expected);
-        return deps.coordinator.runExclusive(deps.agentsRoot, handle, async () => (await ensureRuntimeRootLocked(handle, expected, options)).decision);
-    };
-    const ensureSnapshot = async (handle, snapshot, options = {}) => deps.coordinator.runExclusive(deps.agentsRoot, handle, async () => (await ensureRuntimeRootLocked(handle, snapshot, options)).decision);
-    const reconcileLegacyUnlocked = async (handle, bindings) => {
-        const agentRoot = join(deps.agentsRoot, handle);
-        try {
-            await recoverProjectionSwitch(agentRoot, deps.syncDirectory, manifestOperations);
-        }
-        catch {
-            throw new ProjectProjectionError("skill_projection_failed");
-        }
-        return reconcileUnlocked(handle, bindings, deps.scannedProjects(), false, async () => {
-            const update = await prepareRemoval(agentRoot, readOptions);
-            return Object.freeze({
-                update,
-                operations: manifestOperations,
-                verify: async () => {
-                    if (await readApplied(agentRoot, readOptions) !== null) {
-                        throw new ProjectProjectionError("skill_projection_failed");
-                    }
-                },
-                ...(deps.afterManifestPublishedBeforeCommit === undefined
-                    ? {}
-                    : { afterPublishedBeforeCommit: deps.afterManifestPublishedBeforeCommit }),
-                ...(deps.unlinkSwitchJournal === undefined
-                    ? {}
-                    : { unlinkJournal: deps.unlinkSwitchJournal }),
-            });
-        });
-    };
     return {
-        reconcile(handle, bindings) {
-            return deps.coordinator.runExclusive(deps.agentsRoot, handle, async () => (await reconcileLegacyUnlocked(handle, bindings)).resolutions);
+        async reconcile(handle, bindings) {
+            agentRootFor(handle);
+            const canonical = canonicalConflictFreeBindings(bindings);
+            return toResolutions(await actualResolutionRecords(canonical, deps.scannedProjects(), platform));
         },
-        ensureSnapshot,
-        ensureApplied,
-        projectionDiagnostics: () => lastProjectionDiagnostics,
-        async prepareAndLaunch(agentsRoot, executionId, handle, projection, launch, onWarning) {
-            if (agentsRoot !== deps.agentsRoot) {
-                throw new ProjectProjectionError("skill_projection_failed");
-            }
-            if (Array.isArray(projection)) {
-                return deps.coordinator.runExclusiveUntil(deps.agentsRoot, handle, async () => {
-                    await reconcileLegacyUnlocked(handle, projection);
-                    return launch(undefined);
-                }, runtimeProjectionLifetime);
+        async prepareAndLaunch(requestedAgentsRoot, executionId, handle, projection, launch, onWarning) {
+            if (resolve(requestedAgentsRoot) !== agentsRoot) {
+                throw new ProjectProjectionError("skill_projection_failed", "foreign_agents_root");
+            }
+            const agentRoot = agentRootFor(handle);
+            const bindings = Array.isArray(projection)
+                ? projection
+                : projection.bindings;
+            const canonical = canonicalConflictFreeBindings(bindings);
+            const records = await actualResolutionRecords(canonical, deps.scannedProjects(), platform);
+            for (const record of records) {
+                if (record.mode === "missing") {
+                    onWarning?.({
+                        code: "project_skill_unavailable",
+                        projectId: record.projectId,
+                        skillName: record.skillName,
+                    });
+                }
             }
-            let captured;
+            let root;
             try {
-                captured = await deps.coordinator.runExclusive(deps.agentsRoot, handle, async () => {
-                    const ensured = await ensureRuntimeRootLocked(handle, projection);
-                    const agentRoot = join(deps.agentsRoot, handle);
-                    const alreadyProtected = protectedExecutionIds.has(executionId);
-                    protectedExecutionIds.add(executionId);
-                    let lease;
-                    try {
-                        lease = await runtimeLeases.acquire(agentRoot, {
-                            executionId,
-                            rootId: ensured.runtimeRoot.rootId,
-                        });
-                    }
-                    catch (error) {
-                        let durableLeaseMayExist = true;
-                        try {
-                            durableLeaseMayExist = (await runtimeLeases.protectedExecutionIds(agentRoot))
-                                .includes(executionId);
-                        }
-                        catch {
-                            // Inventory ambiguity retains protection until startup recovery can fail closed.
-                        }
-                        if (!durableLeaseMayExist && !alreadyProtected) {
-                            protectedExecutionIds.delete(executionId);
-                        }
-                        throw error;
-                    }
-                    return Object.freeze({ ...ensured, lease });
-                });
+                root = (await materializeExecutionProjection({
+                    agentRoot,
+                    executionId,
+                    resolutions: records,
+                    platform,
+                    ...(deps.projectDirectory === undefined ? {} : { projectDirectory: deps.projectDirectory }),
+                })).root;
             }
             catch (error) {
-                return mapRuntimeRootError(error);
+                if (error instanceof ExecutionProjectionError) {
+                    throw new ProjectProjectionError("skill_projection_failed", error.reason);
+                }
+                throw new ProjectProjectionError("skill_projection_failed");
             }
-            const releaseLease = async () => {
-                await deps.coordinator.runExclusive(deps.agentsRoot, handle, async () => {
-                    await captured.lease.release();
-                    protectedExecutionIds.delete(captured.lease.executionId);
-                    try {
-                        const agentRoot = join(deps.agentsRoot, handle);
-                        const leases = await runtimeLeases.list(agentRoot);
-                        const applied = await readApplied(agentRoot, readOptions);
-                        await runtimeRootGc.collect(agentRoot, {
-                            currentRootId: applied?.rootId ?? null,
-                            leasedRootIds: leases.map(({ rootId }) => rootId),
-                            keepHistory: 2,
-                        });
-                    }
-                    catch {
-                        // GC is best-effort after a successful lease release.
-                    }
-                });
-            };
+            let child;
             try {
-                if (captured.decision.kind === "use-advanced") {
-                    onWarning?.({ code: captured.decision.warning });
-                }
-                if ("warnings" in captured.decision) {
-                    for (const warning of captured.decision.warnings ?? [])
-                        onWarning?.(warning);
-                }
-                const child = ownershipVerifiedRuntimeProjection(await launch(captured.runtimeRoot));
-                void verifiedRuntimeProjectionLifetime(child).then(releaseLease, () => undefined).catch(() => undefined);
-                return child;
+                child = await launch(root);
             }
             catch (error) {
+                // launch 的 owner 契约:抛错要么发生在 spawn 前,要么已证明进程树停止;唯一例外是 ownership 未确认。
                 if (error instanceof ProjectSkillRuntimeOwnershipUnverifiedError)
                     throw error;
-                await releaseLease().catch(() => undefined);
+                await cleanup(agentRoot, executionId);
                 throw error;
             }
+            const exit = exitPromiseOf(child);
+            if (exit === null) {
+                await cleanup(agentRoot, executionId);
+                return child;
+            }
+            const guardedExit = exit.then(async (value) => {
+                await cleanup(agentRoot, executionId);
+                return value;
+            }, (error) => {
+                throw new ProjectSkillRuntimeOwnershipUnverifiedError(error);
+            });
+            guardedExit.catch(() => undefined);
+            return { ...child, exit: guardedExit };
         },
     };
 }