yam-flow 2.7.0 → 2.8.0

package/dist/lib/skill-installation.js

@@ -7,6 +7,7 @@ export const INSTALL_RECEIPT_NAME = '.yam-flow-install-receipt.json';
 export const INSTALL_LOCK_NAME = '.yam-flow-install.lock';
 export const INSTALL_RECEIPT_SCHEMA = 'yam.install-receipt.v1';
 export const INSTALL_TRANSACTION_PREFIX = '.yam-flow-install-';
+const TRANSACTION_OWNER_MARKER = '.yam-flow-transaction-owner';
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -106,31 +107,60 @@ function readOnlyNoFollowFlags() {
         : 0;
     return fsConstants.O_RDONLY | noFollow;
 }
+async function confirmWindowsPathForHandle(target, opened, before, label) {
+    if (before.birthtimeNs <= 0n) {
+        throw new Error(`${label} requires a positive birthtime on Windows: ${target}`);
+    }
+    let pathHandle;
+    try {
+        pathHandle = await fsp.open(target, fsConstants.O_RDONLY);
+        const pathOpened = await pathHandle.stat({ bigint: true });
+        const confirmed = await fsp.lstat(target, { bigint: true });
+        if (!opened.isFile()
+            || !pathOpened.isFile()
+            || pathOpened.dev !== opened.dev
+            || pathOpened.ino !== opened.ino
+            || confirmed.isSymbolicLink()
+            || !confirmed.isFile()
+            || confirmed.dev !== before.dev
+            || confirmed.ino !== before.ino
+            || confirmed.birthtimeNs !== before.birthtimeNs) {
+            throw new Error(`${label} changed identity while confirming Windows path ownership: ${target}`);
+        }
+        return confirmed;
+    }
+    finally {
+        if (pathHandle)
+            await pathHandle.close();
+    }
+}
 async function captureRegularFile(file, boundary = path.dirname(file)) {
     const parents = await captureRegularParentPath(boundary, file, 'regular file read');
-    const before = await fsp.lstat(file);
+    const before = await fsp.lstat(file, { bigint: true });
     if (!before.isFile() || before.isSymbolicLink())
         throw new Error(`expected a regular file: ${file}`);
     const handle = await fsp.open(file, readOnlyNoFollowFlags());
     try {
-        const opened = await handle.stat();
+        const opened = await handle.stat({ bigint: true });
         if (!opened.isFile())
             throw new Error(`expected a regular file: ${file}`);
         const bytes = await handle.readFile();
-        const afterOpened = await handle.stat();
-        const after = await fsp.lstat(file);
+        const afterOpened = await handle.stat({ bigint: true });
+        const after = process.platform === 'win32'
+            ? await confirmWindowsPathForHandle(file, opened, before, 'regular file')
+            : await fsp.lstat(file, { bigint: true });
         await revalidateRegularParentPath(parents, 'regular file read');
         if (!after.isFile()
             || after.isSymbolicLink()
-            || before.dev !== opened.dev
-            || before.ino !== opened.ino
             || afterOpened.dev !== opened.dev
             || afterOpened.ino !== opened.ino
-            || after.dev !== opened.dev
-            || after.ino !== opened.ino) {
+            || (process.platform !== 'win32' && (before.dev !== opened.dev
+                || before.ino !== opened.ino
+                || after.dev !== opened.dev
+                || after.ino !== opened.ino))) {
             throw new Error(`regular file changed identity while being captured: ${file}`);
         }
-        return { bytes, mode: opened.mode & 0o777 };
+        return { bytes, mode: Number(opened.mode & 511n) };
     }
     finally {
         await handle.close();
@@ -148,20 +178,23 @@ async function copyRegularFile(source, target, sourceBoundary, targetBoundary) {
     const handle = await fsp.open(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollow, sourceFile.mode);
     try {
         await handle.writeFile(sourceFile.bytes);
-        const opened = await handle.stat();
+        const opened = await handle.stat({ bigint: true });
         if (!opened.isFile())
             throw new Error(`install copy target must be a regular file: ${target}`);
         const openedIdentity = { dev: opened.dev, ino: opened.ino };
-        const afterOpened = await handle.stat();
+        const afterOpened = await handle.stat({ bigint: true });
         if (afterOpened.dev !== openedIdentity.dev || afterOpened.ino !== openedIdentity.ino) {
             throw new Error(`install copy target changed descriptor identity: ${target}`);
         }
         await revalidateRegularParentPath(targetParents, 'install copy target');
-        const installed = await fsp.lstat(target);
+        const beforeInstalled = await fsp.lstat(target, { bigint: true });
+        const installed = process.platform === 'win32'
+            ? await confirmWindowsPathForHandle(target, opened, beforeInstalled, 'install copy target')
+            : beforeInstalled;
         if (!installed.isFile()
             || installed.isSymbolicLink()
-            || installed.dev !== openedIdentity.dev
-            || installed.ino !== openedIdentity.ino) {
+            || (process.platform !== 'win32' && (installed.dev !== openedIdentity.dev
+                || installed.ino !== openedIdentity.ino))) {
             throw new Error(`install copy target changed path identity: ${target}`);
         }
     }
@@ -232,8 +265,8 @@ async function expectedInstallManifest(sourceRoot, skills) {
         const skillFile = path.join(sourceRoot, 'skills', skill, 'SKILL.md');
         const skillBytes = await readRegularFileBytes(skillFile, sourceRoot);
         const skillText = skillBytes.toString('utf8');
-        const frontmatter = skillText.match(/^---\n([\s\S]*?)\n---/);
-        const name = frontmatter?.[1].match(/^name:\s*([^\n]+)\s*$/m)?.[1]
+        const frontmatter = skillText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+        const name = frontmatter?.[1].match(/^name:\s*([^\r\n]+)\s*$/m)?.[1]
             ?.trim()
             .replace(/^["']|["']$/g, '');
         if (name !== skill) {
@@ -279,7 +312,7 @@ async function copyTree(source, target, sourceBoundary = source, targetBoundary
     await revalidateRegularParentPath(sourceIdentity, 'install source tree');
     await revalidateRegularParentPath(targetIdentity, 'install target tree');
 }
-async function moveRegularDirectory(source, target, sourceBoundary, targetBoundary, label, onMoved) {
+async function moveRegularDirectory(source, target, sourceBoundary, targetBoundary, label, onMoved, identityOwner) {
     const sourceParents = await captureRegularParentPath(sourceBoundary, source, `${label} source`);
     const sourceStat = await fsp.lstat(source);
     if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
@@ -288,19 +321,35 @@ async function moveRegularDirectory(source, target, sourceBoundary, targetBounda
     const targetParents = await captureRegularParentPath(targetBoundary, target, `${label} target`);
     if (await exists(target))
         throw new Error(`${label} target unexpectedly exists: ${target}`);
-    await fsp.rename(source, target);
-    onMoved?.({ path: target, dev: sourceStat.dev, ino: sourceStat.ino, kind: 'directory' });
-    await revalidateRegularParentPath(sourceParents, `${label} source`);
-    await revalidateRegularParentPath(targetParents, `${label} target`);
-    const targetStat = await fsp.lstat(target);
-    if (!targetStat.isDirectory()
-        || targetStat.isSymbolicLink()
-        || targetStat.dev !== sourceStat.dev
-        || targetStat.ino !== sourceStat.ino) {
-        throw new Error(`${label} directory changed identity while being moved: ${target}`);
+    const recorded = identityOwner ? await captureRecordedEntry(source, 'directory', label) : undefined;
+    let identityTransferred = false;
+    try {
+        await fsp.rename(source, target);
+        if (!recorded)
+            onMoved?.();
+        if (recorded) {
+            recorded.path = target;
+            identityOwner?.push(recorded);
+            identityTransferred = true;
+        }
+        await revalidateRegularParentPath(sourceParents, `${label} source`);
+        await revalidateRegularParentPath(targetParents, `${label} target`);
+        const targetStat = await fsp.lstat(target);
+        if (!targetStat.isDirectory()
+            || targetStat.isSymbolicLink()
+            || targetStat.dev !== sourceStat.dev
+            || targetStat.ino !== sourceStat.ino) {
+            throw new Error(`${label} directory changed identity while being moved: ${target}`);
+        }
+        return recorded;
+    }
+    catch (error) {
+        if (recorded && !identityTransferred)
+            await closeRecordedEntry(recorded);
+        throw error;
     }
 }
-async function moveRegularFile(source, target, sourceBoundary, targetBoundary, label, onMoved) {
+async function moveRegularFile(source, target, sourceBoundary, targetBoundary, label, onMoved, identityOwner) {
     const sourceParents = await captureRegularParentPath(sourceBoundary, source, `${label} source`);
     const sourceStat = await fsp.lstat(source);
     if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
@@ -309,16 +358,32 @@ async function moveRegularFile(source, target, sourceBoundary, targetBoundary, l
     const targetParents = await captureRegularParentPath(targetBoundary, target, `${label} target`);
     if (await exists(target))
         throw new Error(`${label} target unexpectedly exists: ${target}`);
-    await fsp.rename(source, target);
-    onMoved?.({ path: target, dev: sourceStat.dev, ino: sourceStat.ino, kind: 'file' });
-    await revalidateRegularParentPath(sourceParents, `${label} source`);
-    await revalidateRegularParentPath(targetParents, `${label} target`);
-    const targetStat = await fsp.lstat(target);
-    if (!targetStat.isFile()
-        || targetStat.isSymbolicLink()
-        || targetStat.dev !== sourceStat.dev
-        || targetStat.ino !== sourceStat.ino) {
-        throw new Error(`${label} file changed identity while being moved: ${target}`);
+    const recorded = identityOwner ? await captureRecordedEntry(source, 'file', label) : undefined;
+    let identityTransferred = false;
+    try {
+        await fsp.rename(source, target);
+        if (!recorded)
+            onMoved?.();
+        if (recorded) {
+            recorded.path = target;
+            identityOwner?.push(recorded);
+            identityTransferred = true;
+        }
+        await revalidateRegularParentPath(sourceParents, `${label} source`);
+        await revalidateRegularParentPath(targetParents, `${label} target`);
+        const targetStat = await fsp.lstat(target);
+        if (!targetStat.isFile()
+            || targetStat.isSymbolicLink()
+            || targetStat.dev !== sourceStat.dev
+            || targetStat.ino !== sourceStat.ino) {
+            throw new Error(`${label} file changed identity while being moved: ${target}`);
+        }
+        return recorded;
+    }
+    catch (error) {
+        if (recorded && !identityTransferred)
+            await closeRecordedEntry(recorded);
+        throw error;
     }
 }
 function manifestDigest(files) {
@@ -776,28 +841,26 @@ async function acquireInstallLock(destination) {
     }
     let lockIdentity;
     try {
-        const opened = await handle.stat();
+        const lockContents = JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }, null, 2);
+        await handle.writeFile(lockContents);
+        const opened = await handle.stat({ bigint: true });
         if (!opened.isFile())
             throw new Error(`install lock must be a regular file: ${lockPath}`);
-        lockIdentity = { path: lockPath, dev: opened.dev, ino: opened.ino, kind: 'file' };
-        await handle.writeFile(JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }, null, 2));
+        lockIdentity = await captureLockIdentity(lockPath, opened);
+        lockIdentity.contentsSha256 = createHash('sha256').update(lockContents).digest('hex');
         await revalidateRegularParentPath(destinationIdentity, 'skill destination');
-        const current = await fsp.lstat(lockPath);
+        const current = await fsp.lstat(lockPath, { bigint: true });
         if (current.isSymbolicLink()
             || !current.isFile()
             || current.dev !== lockIdentity.dev
-            || current.ino !== lockIdentity.ino) {
+            || current.ino !== lockIdentity.ino
+            || (lockIdentity.birthtimeNs !== undefined && current.birthtimeNs !== lockIdentity.birthtimeNs)) {
             throw new Error(`install lock changed identity while being acquired: ${lockPath}`);
         }
     }
     catch (error) {
         const cleanupErrors = [];
-        try {
-            await handle.close();
-        }
-        catch (closeError) {
-            cleanupErrors.push(message(closeError));
-        }
+        cleanupErrors.push(...await closeFileHandle(handle, lockPath));
         try {
             await revalidateRegularParentPath(destinationIdentity, 'skill destination');
             if (!lockIdentity)
@@ -807,6 +870,12 @@ async function acquireInstallLock(destination) {
         catch (cleanupError) {
             cleanupErrors.push(message(cleanupError));
         }
+        finally {
+            const closeErrors = lockIdentity
+                ? await closeRecordedEntries([lockIdentity])
+                : [];
+            cleanupErrors.push(...closeErrors);
+        }
         if (cleanupErrors.length) {
             throw new Error(`${message(error)}. Install lock cleanup failed: ${cleanupErrors.join('; ')}`);
         }
@@ -858,32 +927,340 @@ async function removeInstalledEntries(entries) {
     }
     return errors;
 }
-async function captureRecordedEntry(target, kind, label) {
-    const stat = await fsp.lstat(target);
+async function captureRecordedEntry(target, kind, label, ownershipMarker) {
+    const noFollow = process.platform !== 'win32' && typeof fsConstants.O_NOFOLLOW === 'number'
+        ? fsConstants.O_NOFOLLOW
+        : 0;
+    const directoryOnly = kind === 'directory'
+        && process.platform !== 'win32'
+        && typeof fsConstants.O_DIRECTORY === 'number'
+        ? fsConstants.O_DIRECTORY
+        : 0;
+    let handle;
+    try {
+        if (process.platform !== 'win32') {
+            handle = await fsp.open(target, fsConstants.O_RDONLY | noFollow | directoryOnly);
+        }
+        if (handle)
+            return await captureRecordedEntryFromHandle(target, kind, label, handle);
+        const stat = await fsp.lstat(target, { bigint: true });
+        const typeMatches = kind === 'directory'
+            ? stat.isDirectory() && !stat.isSymbolicLink()
+            : stat.isFile() && !stat.isSymbolicLink();
+        if (!typeMatches || stat.birthtimeNs <= 0n) {
+            throw new Error(`${label} must be one stable regular ${kind} with a positive birthtime: ${target}`);
+        }
+        const entry = {
+            path: target,
+            dev: stat.dev,
+            ino: stat.ino,
+            kind,
+            birthtimeNs: stat.birthtimeNs,
+            ownershipMarker
+        };
+        if (kind === 'file') {
+            const bytes = await readRegularFileBytes(target, path.dirname(target));
+            entry.contentsSha256 = createHash('sha256').update(bytes).digest('hex');
+        }
+        else if (!ownershipMarker) {
+            entry.treeDigest = manifestDigest(await collectTreeManifest(target));
+        }
+        return entry;
+    }
+    catch (error) {
+        if (handle)
+            await handle.close().catch(() => { });
+        throw error;
+    }
+}
+async function captureRecordedEntryFromHandle(target, kind, label, handle) {
+    const opened = await handle.stat({ bigint: true });
+    const current = await fsp.lstat(target, { bigint: true });
     const typeMatches = kind === 'directory'
-        ? stat.isDirectory() && !stat.isSymbolicLink()
-        : stat.isFile() && !stat.isSymbolicLink();
-    if (!typeMatches)
-        throw new Error(`${label} must be a regular ${kind}: ${target}`);
-    return { path: target, dev: stat.dev, ino: stat.ino, kind };
+        ? opened.isDirectory() && current.isDirectory() && !current.isSymbolicLink()
+        : opened.isFile() && current.isFile() && !current.isSymbolicLink();
+    const birthtimeAvailable = opened.birthtimeNs > 0n && current.birthtimeNs > 0n;
+    if (!typeMatches
+        || opened.dev !== current.dev
+        || opened.ino !== current.ino
+        || (birthtimeAvailable && opened.birthtimeNs !== current.birthtimeNs)) {
+        throw new Error(`${label} must be one stable regular ${kind}: ${target}`);
+    }
+    return {
+        path: target,
+        dev: opened.dev,
+        ino: opened.ino,
+        kind,
+        birthtimeNs: birthtimeAvailable ? opened.birthtimeNs : undefined,
+        handle
+    };
+}
+async function captureLockIdentity(target, created) {
+    const current = await fsp.lstat(target, { bigint: true });
+    if (!created.isFile()
+        || current.isSymbolicLink()
+        || !current.isFile()
+        || (process.platform !== 'win32' && (created.dev !== current.dev
+            || created.ino !== current.ino))) {
+        throw new Error(`install lock changed identity after exclusive creation: ${target}`);
+    }
+    let pinHandle;
+    try {
+        if (process.platform !== 'win32') {
+            const noFollow = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+            pinHandle = await fsp.open(target, fsConstants.O_RDONLY | noFollow);
+            const pinned = await pinHandle.stat({ bigint: true });
+            if (!pinned.isFile()
+                || pinned.dev !== created.dev
+                || pinned.ino !== created.ino) {
+                throw new Error(`install lock pin descriptor does not match exclusive creation: ${target}`);
+            }
+        }
+        else {
+            const confirmed = await confirmWindowsPathForHandle(target, created, current, 'install lock');
+            return {
+                path: target,
+                dev: confirmed.dev,
+                ino: confirmed.ino,
+                kind: 'file',
+                birthtimeNs: confirmed.birthtimeNs
+            };
+        }
+        return {
+            path: target,
+            dev: created.dev,
+            ino: created.ino,
+            kind: 'file',
+            handle: pinHandle
+        };
+    }
+    catch (error) {
+        if (pinHandle)
+            await pinHandle.close().catch(() => { });
+        throw error;
+    }
 }
 async function removeRecordedEntry(entry, label) {
-    let current;
     try {
-        current = await fsp.lstat(entry.path);
+        let current;
+        try {
+            current = await fsp.lstat(entry.path, { bigint: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        const opened = entry.handle ? await entry.handle.stat({ bigint: true }) : undefined;
+        const typeMatches = entry.kind === 'directory'
+            ? current.isDirectory() && !current.isSymbolicLink()
+            : current.isFile() && !current.isSymbolicLink();
+        if (!typeMatches
+            || current.dev !== entry.dev
+            || current.ino !== entry.ino
+            || (entry.birthtimeNs !== undefined && current.birthtimeNs !== entry.birthtimeNs)
+            || (opened && (opened.dev !== current.dev
+                || opened.ino !== current.ino
+                || (entry.birthtimeNs !== undefined && opened.birthtimeNs !== current.birthtimeNs)))) {
+            throw new Error(`${label} identity mismatch; preserved current path: ${entry.path}`);
+        }
+        if (entry.contentsSha256) {
+            try {
+                const bytes = await readRegularFileBytes(entry.path, path.dirname(entry.path));
+                const currentSha256 = createHash('sha256').update(bytes).digest('hex');
+                if (currentSha256 !== entry.contentsSha256)
+                    throw new Error('content digest changed');
+            }
+            catch (error) {
+                throw new Error(`${label} identity mismatch (content: ${message(error)}); preserved current path: ${entry.path}`);
+            }
+        }
+        if (entry.treeDigest) {
+            try {
+                const currentTreeDigest = manifestDigest(await collectTreeManifest(entry.path));
+                if (currentTreeDigest !== entry.treeDigest)
+                    throw new Error('tree digest changed');
+            }
+            catch (error) {
+                throw new Error(`${label} identity mismatch (tree: ${message(error)}); preserved current path: ${entry.path}`);
+            }
+        }
+        if (entry.ownershipMarker) {
+            try {
+                const markerPath = path.join(entry.path, entry.ownershipMarker.name);
+                const markerBytes = await readRegularFileBytes(markerPath, entry.path);
+                const markerSha256 = createHash('sha256').update(markerBytes).digest('hex');
+                if (markerSha256 !== entry.ownershipMarker.sha256)
+                    throw new Error('ownership marker digest changed');
+            }
+            catch (error) {
+                throw new Error(`${label} identity mismatch (ownership marker: ${message(error)}); preserved current path: ${entry.path}`);
+            }
+        }
+        await fsp.rm(entry.path, { recursive: entry.kind === 'directory', force: entry.kind === 'file' });
+    }
+    finally {
+        await closeRecordedEntry(entry);
+    }
+}
+async function captureTransactionRoot(target, label) {
+    const markerContents = `${randomUUID()}\n`;
+    const markerPath = path.join(target, TRANSACTION_OWNER_MARKER);
+    await fsp.writeFile(markerPath, markerContents, { flag: 'wx', mode: 0o600 });
+    return captureRecordedEntry(target, 'directory', label, {
+        name: TRANSACTION_OWNER_MARKER,
+        sha256: createHash('sha256').update(markerContents).digest('hex')
+    });
+}
+async function closeRecordedEntry(entry) {
+    const handle = entry.handle;
+    entry.handle = undefined;
+    if (handle)
+        await handle.close();
+}
+async function closeRecordedEntries(entries) {
+    const errors = [];
+    for (const entry of entries) {
+        if (!entry)
+            continue;
+        try {
+            await closeRecordedEntry(entry);
+        }
+        catch (error) {
+            errors.push(`${entry.path}: ${message(error)}`);
+        }
+    }
+    return errors;
+}
+async function closeFileHandle(handle, pathLabel) {
+    try {
+        await handle.close();
+        return [];
+    }
+    catch (error) {
+        return [`${pathLabel}: ${message(error)}`];
+    }
+}
+export async function planSkillSetInstallation(options) {
+    const sourceRoot = path.resolve(options.sourceRoot);
+    const destination = safeRoot(options.destination, 'skill destination');
+    const codexMirror = options.codexMirror ? safeRoot(options.codexMirror, 'Codex mirror') : '';
+    const skills = unique(options.skills);
+    const cleanupCandidates = unique([...(options.legacySkills || []), ...(options.retiredSkills || [])]);
+    const replaceSkills = unique(options.replaceSkills || []);
+    validateManagedNames([...skills, ...cleanupCandidates, ...replaceSkills]);
+    const expected = await expectedInstallManifest(sourceRoot, skills);
+    const sourceDigest = manifestDigest(expected);
+    const receiptPath = path.join(destination, INSTALL_RECEIPT_NAME);
+    const operations = [];
+    const blockers = await nonMutatingInstallGateBlockers(destination);
+    let ownership;
+    try {
+        if (blockers.length)
+            throw new Error(blockers[0]);
+        ownership = await preflightInstallOwnership(destination, options.packageName, skills, cleanupCandidates, replaceSkills);
+    }
+    catch (error) {
+        if (!blockers.length)
+            blockers.push(message(error));
+    }
+    if (ownership) {
+        const replaceNames = new Set(ownership.replaceNames);
+        for (const skill of skills) {
+            const target = path.join(destination, skill);
+            const existing = await exists(target);
+            operations.push({
+                action: !existing
+                    ? 'create'
+                    : replaceSkills.includes(skill)
+                        ? 'replace_explicitly_authorized'
+                        : 'replace_managed',
+                skill,
+                path: target,
+                reason: !existing
+                    ? 'active skill is not installed'
+                    : replaceSkills.includes(skill)
+                        ? 'operator supplied an explicit per-skill replacement override'
+                        : 'existing skill ownership and complete content integrity match the yam receipt'
+            });
+        }
+        for (const skill of cleanupCandidates) {
+            if (!replaceNames.has(skill) || skills.includes(skill))
+                continue;
+            operations.push({
+                action: 'remove_retired',
+                skill,
+                path: path.join(destination, skill),
+                reason: 'retired or legacy skill is still proven yam-owned by the current receipt'
+            });
+        }
+        operations.push({
+            action: 'write_receipt',
+            skill: '',
+            path: receiptPath,
+            reason: ownership.receipt ? 'replace the verified yam ownership receipt' : 'create the yam ownership receipt'
+        });
+    }
+    const preservedPaths = codexMirror && codexMirror !== destination ? [codexMirror] : [];
+    const replaceNames = new Set(ownership?.replaceNames || []);
+    for (const skill of cleanupCandidates) {
+        if (replaceNames.has(skill) || !await exists(path.join(destination, skill)))
+            continue;
+        preservedPaths.push(path.join(destination, skill));
+    }
+    preservedPaths.sort(compareStableText);
+    const planBasis = {
+        package: { name: options.packageName, version: options.version },
+        source: { root: sourceRoot, digest: sourceDigest, file_count: expected.length },
+        destination,
+        receipt_path: receiptPath,
+        operations,
+        preserved_paths: preservedPaths,
+        blockers
+    };
+    const planDigest = createHash('sha256').update(JSON.stringify(planBasis)).digest('hex');
+    const ready = blockers.length === 0;
+    return {
+        schema: 'yam.install-plan.v1',
+        generated_at: (options.now || (() => new Date()))().toISOString(),
+        mutation_authorized: false,
+        ...planBasis,
+        ready,
+        truth_status: ready ? 'verified' : 'blocked',
+        plan_digest: planDigest,
+        next_action: ready
+            ? 'review this non-mutating plan, then run `yam install` without --dry-run to authorize the transaction'
+            : 'resolve the listed lock, recovery, destination, or ownership blocker without deleting unreviewed state, then regenerate the plan'
+    };
+}
+async function nonMutatingInstallGateBlockers(destination) {
+    let stat;
+    try {
+        stat = await fsp.lstat(destination);
     }
     catch (error) {
         if (error.code === 'ENOENT')
-            return;
-        throw error;
+            return [];
+        return [`skill destination cannot be inspected: ${message(error)}`];
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        return [`skill destination must be a regular physical directory: ${destination}`];
+    }
+    const blockers = [];
+    const lockPath = path.join(destination, INSTALL_LOCK_NAME);
+    if (await exists(lockPath)) {
+        blockers.push(`another yam install may be active; lock exists at ${lockPath}`);
+    }
+    try {
+        const recoveryArtifacts = await findInstallRecoveryArtifacts(destination);
+        if (recoveryArtifacts.length) {
+            blockers.push(`unfinished yam install transaction requires inspection: ${recoveryArtifacts.join(', ')}`);
+        }
     }
-    const typeMatches = entry.kind === 'directory'
-        ? current.isDirectory() && !current.isSymbolicLink()
-        : current.isFile() && !current.isSymbolicLink();
-    if (!typeMatches || current.dev !== entry.dev || current.ino !== entry.ino) {
-        throw new Error(`${label} identity mismatch; preserved current path: ${entry.path}`);
+    catch (error) {
+        blockers.push(`install recovery state cannot be inspected: ${message(error)}`);
     }
-    await fsp.rm(entry.path, { recursive: entry.kind === 'directory', force: entry.kind === 'file' });
+    return blockers;
 }
 export async function installSkillSetTransactional(options) {
     const sourceRoot = path.resolve(options.sourceRoot);
@@ -910,13 +1287,14 @@ export async function installSkillSetTransactional(options) {
         const expected = await expectedInstallManifest(sourceRoot, skills);
         const transactionId = options.transactionId || randomUUID();
         const transactionRoot = await fsp.mkdtemp(path.join(destination, '.yam-flow-install-'));
-        const transactionEntry = await captureRecordedEntry(transactionRoot, 'directory', 'install transaction root');
+        const transactionEntry = await captureTransactionRoot(transactionRoot, 'install transaction root');
         const stagedRoot = path.join(transactionRoot, 'staged');
         const backupRoot = path.join(transactionRoot, 'backup');
         const stagedReceiptPath = path.join(transactionRoot, 'receipt.json');
         const destinationReceiptPath = path.join(destination, INSTALL_RECEIPT_NAME);
         const receiptBackupPath = path.join(transactionRoot, 'receipt.backup');
         const installedEntries = [];
+        const receiptInstalledEntries = [];
         let destinationBackups = [];
         let receiptBackedUp = false;
         let receiptInstalled;
@@ -965,11 +1343,16 @@ export async function installSkillSetTransactional(options) {
             for (const skill of skills) {
                 await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
                 const target = path.join(destination, skill);
-                await moveRegularDirectory(path.join(stagedRoot, skill), target, stagedRoot, destination, 'staged skill install', (entry) => installedEntries.push(entry));
+                const installedEntry = await moveRegularDirectory(path.join(stagedRoot, skill), target, stagedRoot, destination, 'staged skill install', undefined, installedEntries);
+                if (!installedEntry)
+                    throw new Error(`staged skill install identity was not recorded: ${target}`);
                 await options.failpoint?.({ phase: 'skill-installed', skill });
             }
             await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
-            await moveRegularFile(stagedReceiptPath, destinationReceiptPath, transactionRoot, destination, 'staged install receipt', (entry) => { receiptInstalled = entry; });
+            receiptInstalled = await moveRegularFile(stagedReceiptPath, destinationReceiptPath, transactionRoot, destination, 'staged install receipt', undefined, receiptInstalledEntries);
+            if (!receiptInstalled) {
+                throw new Error(`staged install receipt identity was not recorded: ${destinationReceiptPath}`);
+            }
             await options.failpoint?.({ phase: 'receipt-installed' });
             await options.failpoint?.({ phase: 'before-verify' });
             await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
@@ -983,6 +1366,10 @@ export async function installSkillSetTransactional(options) {
             });
             if (!inspection.ok)
                 throw new Error(`post-install verification failed: ${inspection.issues.join('; ')}`);
+            const ownershipHandleErrors = await closeRecordedEntries([receiptInstalled, ...installedEntries]);
+            if (ownershipHandleErrors.length) {
+                cleanupWarnings.push(`verified install identity handle cleanup failed: ${ownershipHandleErrors.join('; ')}`);
+            }
             try {
                 await removeRecordedEntry(transactionEntry, 'install transaction cleanup');
             }
@@ -999,6 +1386,7 @@ export async function installSkillSetTransactional(options) {
         }
         catch (error) {
             const rollbackErrors = [];
+            receiptInstalled ||= receiptInstalledEntries[0];
             let destinationStillOwned = true;
             try {
                 await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
@@ -1037,6 +1425,8 @@ export async function installSkillSetTransactional(options) {
                 }
                 throw new Error(`yam install failed; previous installation state restored: ${message(error)}`);
             }
+            const retainedHandleErrors = await closeRecordedEntries([transactionEntry, receiptInstalled, ...installedEntries]);
+            rollbackErrors.push(...retainedHandleErrors.map((item) => `identity handle cleanup failed: ${item}`));
             throw new Error(`yam install failed and rollback is incomplete: ${message(error)}. `
                 + `Recovery artifacts were kept at ${transactionRoot}. `
                 + `Rollback errors: ${rollbackErrors.join('; ')}`);
@@ -1046,12 +1436,7 @@ export async function installSkillSetTransactional(options) {
         primaryError = error;
     }
     const lockCleanupErrors = [];
-    try {
-        await lock.handle.close();
-    }
-    catch (error) {
-        lockCleanupErrors.push(message(error));
-    }
+    lockCleanupErrors.push(...await closeFileHandle(lock.handle, lock.lockPath));
     try {
         await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
         await removeRecordedEntry(lock.lockIdentity, 'install lock cleanup');
@@ -1059,6 +1444,9 @@ export async function installSkillSetTransactional(options) {
     catch (error) {
         lockCleanupErrors.push(message(error));
     }
+    finally {
+        lockCleanupErrors.push(...await closeRecordedEntries([lock.lockIdentity]));
+    }
     if (lockCleanupErrors.length) {
         const warning = `install lock cleanup failed at ${lock.lockPath}: ${lockCleanupErrors.join('; ')}`;
         if (primaryError)
@@ -1095,7 +1483,7 @@ export async function uninstallSkillSetSafely(options) {
         }
         await preflightSafeUninstallOwnership(destination, options.packageName, skills);
         const transactionRoot = await fsp.mkdtemp(path.join(destination, '.yam-flow-install-uninstall-'));
-        const transactionEntry = await captureRecordedEntry(transactionRoot, 'directory', 'uninstall transaction root');
+        const transactionEntry = await captureTransactionRoot(transactionRoot, 'uninstall transaction root');
         const backupRoot = path.join(transactionRoot, 'backup');
         const receiptPath = path.join(destination, INSTALL_RECEIPT_NAME);
         const receiptBackup = path.join(transactionRoot, INSTALL_RECEIPT_NAME);
@@ -1170,6 +1558,8 @@ export async function uninstallSkillSetSafely(options) {
                 }
                 throw new Error(`yam uninstall failed; previous installation state restored: ${message(error)}`);
             }
+            const retainedHandleErrors = await closeRecordedEntries([transactionEntry]);
+            rollbackErrors.push(...retainedHandleErrors.map((item) => `identity handle cleanup failed: ${item}`));
             throw new Error(`yam uninstall failed and rollback is incomplete: ${message(error)}. `
                 + `Recovery artifacts were kept at ${transactionRoot}. Rollback errors: ${rollbackErrors.join('; ')}`);
         }
@@ -1178,12 +1568,7 @@ export async function uninstallSkillSetSafely(options) {
         primaryError = error;
     }
     const lockCleanupErrors = [];
-    try {
-        await lock.handle.close();
-    }
-    catch (error) {
-        lockCleanupErrors.push(message(error));
-    }
+    lockCleanupErrors.push(...await closeFileHandle(lock.handle, lock.lockPath));
     try {
         await revalidateRegularParentPath(lock.destinationIdentity, 'skill destination');
         await removeRecordedEntry(lock.lockIdentity, 'install lock cleanup');
@@ -1191,6 +1576,9 @@ export async function uninstallSkillSetSafely(options) {
     catch (error) {
         lockCleanupErrors.push(message(error));
     }
+    finally {
+        lockCleanupErrors.push(...await closeRecordedEntries([lock.lockIdentity]));
+    }
     if (lockCleanupErrors.length) {
         const warning = `install lock cleanup failed at ${lock.lockPath}: ${lockCleanupErrors.join('; ')}`;
         if (primaryError)