commandmate 0.11.3 → 0.12.0

package/dist/server/src/lib/skills/install-apply.js

@@ -0,0 +1,670 @@
+"use strict";
+/**
+ * Atomic commit of a planned Skill install into one worktree (Issue #1235)
+ *
+ * The write half of the plan/apply pair. #1233 fixed *what* would be written —
+ * the exact payload bytes, the exact receipt bytes and the tree hash they add up
+ * to — and this module is the only place those bytes reach a repository.
+ *
+ * Four properties carry the safety argument:
+ *
+ * - **The destination is derived, never received.** The install root comes from
+ *   a server-resolved worktree path plus a Skill ID re-checked against
+ *   {@link SKILL_ID_PATTERN}. Re-checking the grammar rather than only the
+ *   joined result is deliberate: `path.join` normalizes `..` away, so
+ *   `.agents/skills/../x` and `.agents/x` compare equal and a containment check
+ *   alone would accept an ID that walked out of the Skills directory.
+ * - **Every write is exclusive and does not follow links.** Files are created
+ *   with `O_CREAT|O_EXCL|O_NOFOLLOW`, so a symlink or a file planted between the
+ *   directory scan and the write cannot be written *through*; mode and digest
+ *   are re-read afterwards, so a file that changed underneath us never reaches
+ *   the receipt.
+ * - **The commit point is one rename.** Staging lives in the reserved
+ *   `.agents/skills/.commandmate-staging/` namespace, on the same filesystem as
+ *   the destination, so `rename(2)` is atomic. Before it lands the destination
+ *   is proven absent: an existing directory — managed or hand-made — is refused,
+ *   never merged into and never implicitly overwritten.
+ * - **Nothing is executed.** No script, hook, install step or archive-carried
+ *   mode is ever run or honoured. Modes are assigned from the manifest's
+ *   declared executable bit and nothing else.
+ *
+ * A failure *after* the rename is not a rollback. The payload exists, and the
+ * caller must report it as committed and hand the remainder to #1234
+ * reconciliation rather than claiming the worktree is unchanged.
+ *
+ * @module lib/skills/install-apply
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_INSTALL_NEXT_ACTION_KEYS = exports.SKILL_INSTALL_RELOAD_MESSAGE_KEYS = exports.SkillInstallError = exports.SKILL_INSTALL_ERROR_STATUS = exports.SkillInstallErrorCode = exports.SKILL_INSTALL_OPERATION_ID_PATTERN = exports.SKILL_INSTALL_EXECUTABLE_MODE = exports.SKILL_INSTALL_FILE_MODE = exports.SKILL_INSTALL_DIR_MODE = void 0;
+exports.isSkillInstallError = isSkillInstallError;
+exports.buildSkillReloadGuidance = buildSkillReloadGuidance;
+exports.resolveSkillInstallTarget = resolveSkillInstallTarget;
+exports.resolveSkillInstallTargetFor = resolveSkillInstallTargetFor;
+exports.inspectSkillDestination = inspectSkillDestination;
+exports.hasCommittedSkillPayload = hasCommittedSkillPayload;
+exports.writeSkillPayloadFile = writeSkillPayloadFile;
+exports.applySkillInstall = applySkillInstall;
+exports.completeSecondarySkillInstallRoots = completeSecondarySkillInstallRoots;
+exports.cleanupSkillInstallStaging = cleanupSkillInstallStaging;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("../../lib/skills/constants");
+const integrity_1 = require("../../lib/skills/integrity");
+const operation_store_1 = require("../../lib/skills/operation-store");
+const preview_diff_1 = require("../../lib/skills/preview-diff");
+const install_plan_1 = require("../../lib/skills/install-plan");
+// =============================================================================
+// Modes and layout
+// =============================================================================
+/** Payload directories are owner-only, like the staging that produced them. */
+exports.SKILL_INSTALL_DIR_MODE = 0o700;
+/** Ordinary payload files. */
+exports.SKILL_INSTALL_FILE_MODE = 0o600;
+/** Files the manifest declared executable. Only the owner execute bit is added. */
+exports.SKILL_INSTALL_EXECUTABLE_MODE = 0o700;
+/**
+ * Grammar of the staging directory name.
+ *
+ * The name is a server-generated operation ID and never a client string, but it
+ * becomes a path segment, so it is checked rather than trusted.
+ */
+exports.SKILL_INSTALL_OPERATION_ID_PATTERN = /^[0-9a-zA-Z-]{8,64}$/;
+/** `O_NOFOLLOW` is POSIX-only; on platforms without it the flag is a no-op. */
+const O_NOFOLLOW = fs_1.constants.O_NOFOLLOW ?? 0;
+// =============================================================================
+// Errors
+// =============================================================================
+/** Client-safe reasons an apply refused to write or could not finish. */
+exports.SkillInstallErrorCode = {
+    /** The install root could not be derived safely from the worktree and Skill ID. */
+    TARGET_UNSAFE: 'SKILL_INSTALL_TARGET_UNSAFE',
+    /** An ancestor of the install root is a symlink or is not a directory. */
+    ANCESTOR_UNSAFE: 'SKILL_INSTALL_ANCESTOR_UNSAFE',
+    /** A CommandMate-managed install is already present. Updating is out of scope. */
+    DESTINATION_EXISTS: 'SKILL_INSTALL_DESTINATION_EXISTS',
+    /** Something CommandMate does not manage occupies the install root. */
+    DESTINATION_UNMANAGED: 'SKILL_INSTALL_DESTINATION_UNMANAGED',
+    /** Staging and destination are on different filesystems, so rename is not atomic. */
+    CROSS_DEVICE: 'SKILL_INSTALL_CROSS_DEVICE',
+    /** Staging could not be created or written. */
+    STAGING_IO: 'SKILL_INSTALL_STAGING_IO',
+    /** What landed in staging is not what the plan fixed. */
+    PAYLOAD_MISMATCH: 'SKILL_INSTALL_PAYLOAD_MISMATCH',
+    /** The atomic rename itself failed. Nothing was published. */
+    COMMIT_FAILED: 'SKILL_INSTALL_COMMIT_FAILED',
+};
+/** HTTP status each reason maps to, so every caller answers alike. */
+exports.SKILL_INSTALL_ERROR_STATUS = {
+    [exports.SkillInstallErrorCode.TARGET_UNSAFE]: 400,
+    [exports.SkillInstallErrorCode.ANCESTOR_UNSAFE]: 409,
+    [exports.SkillInstallErrorCode.DESTINATION_EXISTS]: 409,
+    [exports.SkillInstallErrorCode.DESTINATION_UNMANAGED]: 409,
+    [exports.SkillInstallErrorCode.CROSS_DEVICE]: 500,
+    [exports.SkillInstallErrorCode.STAGING_IO]: 500,
+    [exports.SkillInstallErrorCode.PAYLOAD_MISMATCH]: 500,
+    [exports.SkillInstallErrorCode.COMMIT_FAILED]: 500,
+};
+/** An apply rejection. The message is built from the code — never from a path. */
+class SkillInstallError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        super(`Skill install rejected: ${code}`);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'SkillInstallError';
+    }
+    get status() {
+        return exports.SKILL_INSTALL_ERROR_STATUS[this.code];
+    }
+}
+exports.SkillInstallError = SkillInstallError;
+function isSkillInstallError(value) {
+    return value instanceof SkillInstallError;
+}
+function fail(code, detail) {
+    throw new SkillInstallError(code, detail);
+}
+// =============================================================================
+// Reload guidance
+// =============================================================================
+/** i18n key per agent support level, so UI and CLI say the same thing (UX-01). */
+exports.SKILL_INSTALL_RELOAD_MESSAGE_KEYS = {
+    native: 'skills.install.reload.native',
+    commandmate_runtime: 'skills.install.reload.commandmateRuntime',
+    unsupported: 'skills.install.reload.unsupported',
+    unknown: 'skills.install.reload.unknown',
+};
+/** i18n key for what the user should do next, per outcome (UX-07). */
+exports.SKILL_INSTALL_NEXT_ACTION_KEYS = {
+    succeeded: 'skills.install.nextAction.succeeded',
+    committedReconciling: 'skills.install.nextAction.committedReconciling',
+    failed: 'skills.install.nextAction.failed',
+};
+/**
+ * Derive reload guidance from the receipt.
+ *
+ * The receipt is used rather than the Catalog because it is the record of what
+ * actually landed: guidance for a version other than the installed one would be
+ * worse than none.
+ */
+function buildSkillReloadGuidance(receipt) {
+    return {
+        skillId: receipt.skill_id,
+        version: receipt.version,
+        installRoot: receipt.install_root,
+        agents: receipt.agent_compatibility.map((entry) => ({
+            agent: entry.agent,
+            support: entry.support,
+            messageKey: exports.SKILL_INSTALL_RELOAD_MESSAGE_KEYS[entry.support],
+        })),
+    };
+}
+// =============================================================================
+// Path safety
+// =============================================================================
+/**
+ * Absolute install root for a validated Skill ID inside a server-resolved worktree.
+ *
+ * Delegates to #1233's resolver so plan and apply cannot disagree about where a
+ * Skill lives, and re-checks the ID here as well: this module must be safe to
+ * call without a plan, for instance from reconciliation.
+ */
+function resolveSkillInstallTarget(worktreePath, skillId) {
+    return resolveSkillInstallTargetFor(worktreePath, constants_1.SKILL_INSTALL_ROOT_PREFIX, skillId);
+}
+/**
+ * Absolute install root for a validated Skill ID under one root prefix (#1460).
+ *
+ * The per-root generalization of {@link resolveSkillInstallTarget}: `.claude/skills`
+ * gets exactly the grammar re-check and containment rejection `.agents/skills`
+ * always had, so neither root can be walked out of by a crafted ID.
+ */
+function resolveSkillInstallTargetFor(worktreePath, rootPrefix, skillId) {
+    if (!constants_1.SKILL_ID_PATTERN.test(skillId) || skillId.length > constants_1.SKILL_ID_MAX_LENGTH) {
+        fail(exports.SkillInstallErrorCode.TARGET_UNSAFE, { reason: 'skill-id' });
+    }
+    try {
+        return (0, preview_diff_1.resolveSkillInstallRootFor)(worktreePath, rootPrefix, skillId);
+    }
+    catch {
+        return fail(exports.SkillInstallErrorCode.TARGET_UNSAFE, { reason: 'install-root' });
+    }
+}
+/**
+ * Prove no ancestor of the install root was swapped for a link.
+ *
+ * `lstat` at every level from the worktree down: a symlink anywhere on the chain
+ * would let the rename publish the payload outside the registered worktree, and
+ * `realpath` alone would silently *follow* it instead of refusing.
+ */
+function assertAncestorsAreRealDirectories(worktreeRealPath, worktreePath, rootPrefix = constants_1.SKILL_INSTALL_ROOT_PREFIX) {
+    let resolved;
+    try {
+        resolved = (0, fs_1.realpathSync)(worktreePath);
+    }
+    catch {
+        return fail(exports.SkillInstallErrorCode.ANCESTOR_UNSAFE, { reason: 'worktree-unresolvable' });
+    }
+    if (resolved !== worktreeRealPath) {
+        fail(exports.SkillInstallErrorCode.ANCESTOR_UNSAFE, { reason: 'worktree-identity' });
+    }
+    let walked = worktreeRealPath;
+    for (const segment of rootPrefix.split('/')) {
+        walked = path_1.default.join(walked, segment);
+        let stats;
+        try {
+            stats = (0, fs_1.lstatSync)(walked);
+        }
+        catch {
+            // Not yet created is fine; it is created below with a plain mkdir.
+            return;
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            fail(exports.SkillInstallErrorCode.ANCESTOR_UNSAFE, { reason: 'not-a-directory' });
+        }
+    }
+}
+/**
+ * Describe the install root without following anything.
+ *
+ * A non-directory at the install root (a file, a symlink) counts as present and
+ * unmanaged: it is not something an install may quietly replace.
+ */
+function inspectSkillDestination(installRootAbs) {
+    let stats;
+    try {
+        stats = (0, fs_1.lstatSync)(installRootAbs);
+    }
+    catch {
+        return { present: false, managed: false, version: null };
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        return { present: true, managed: false, version: null };
+    }
+    try {
+        const receipt = (0, install_plan_1.parseInstalledReceipt)((0, fs_1.readFileSync)(path_1.default.join(installRootAbs, install_plan_1.SKILL_RECEIPT_FILENAME)));
+        if (receipt)
+            return { present: true, managed: true, version: receipt.version };
+    }
+    catch {
+        // No readable receipt: the directory exists but CommandMate did not write it.
+    }
+    return { present: true, managed: false, version: null };
+}
+/**
+ * Whether the payload a committed operation wrote is still on disk.
+ *
+ * The port #1234's reconciler needs: it decides between "converge forward" and
+ * "genuinely rolled back", and only the receipt digest can distinguish the
+ * install that committed from a different one that happens to share the path.
+ */
+function hasCommittedSkillPayload(worktreePath, skillId, receiptDigest) {
+    let installRootAbs;
+    try {
+        installRootAbs = resolveSkillInstallTarget(worktreePath, skillId);
+    }
+    catch {
+        return false;
+    }
+    let bytes;
+    try {
+        bytes = (0, fs_1.readFileSync)(path_1.default.join(installRootAbs, install_plan_1.SKILL_RECEIPT_FILENAME));
+    }
+    catch {
+        return false;
+    }
+    if ((0, install_plan_1.parseInstalledReceipt)(bytes) === null)
+        return false;
+    return receiptDigest === null || (0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)(bytes), receiptDigest);
+}
+// =============================================================================
+// Staging
+// =============================================================================
+function makeDirectory(target, mode, recursive) {
+    try {
+        (0, fs_1.mkdirSync)(target, { mode, recursive });
+    }
+    catch {
+        fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'mkdir' });
+    }
+    let stats;
+    try {
+        stats = (0, fs_1.lstatSync)(target);
+    }
+    catch {
+        return fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'mkdir-verify' });
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'not-a-directory' });
+    }
+}
+/**
+ * Write one file and prove afterwards that it is the file we meant to write.
+ *
+ * `O_EXCL` means an existing path is never written to, and `O_NOFOLLOW` means a
+ * symlink planted at that path is refused rather than followed — together they
+ * make "the write landed somewhere else" unrepresentable. The post-write checks
+ * are not belt-and-braces either: `nlink !== 1` would mean the path was
+ * hard-linked elsewhere, and a digest read back through the same path is the
+ * only evidence that what a later reader sees matches the plan.
+ *
+ * @internal Exported for the guard tests; callers use {@link applySkillInstall}.
+ */
+function writeSkillPayloadFile(target, bytes, executable) {
+    const mode = executable ? exports.SKILL_INSTALL_EXECUTABLE_MODE : exports.SKILL_INSTALL_FILE_MODE;
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(target, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | O_NOFOLLOW, mode);
+    }
+    catch {
+        return fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'open' });
+    }
+    try {
+        let written = 0;
+        while (written < bytes.byteLength) {
+            written += (0, fs_1.writeSync)(fd, bytes, written, bytes.byteLength - written);
+        }
+    }
+    catch {
+        (0, fs_1.closeSync)(fd);
+        return fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'write' });
+    }
+    (0, fs_1.closeSync)(fd);
+    const stats = (0, fs_1.lstatSync)(target);
+    if (!stats.isFile() || stats.nlink !== 1 || stats.size !== bytes.byteLength) {
+        fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'verify-stat' });
+    }
+    if (((stats.mode & 0o111) !== 0) !== executable) {
+        fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'verify-mode' });
+    }
+    if (!(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)((0, fs_1.readFileSync)(target)), (0, integrity_1.computeSha256Hex)(bytes))) {
+        fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'readback' });
+    }
+}
+/** Re-read a staged tree from disk, so verification never trusts its own inputs. */
+function readStagedTree(stagingDir) {
+    const files = [];
+    const walk = (dirAbs, relPrefix) => {
+        for (const entry of (0, fs_1.readdirSync)(dirAbs, { withFileTypes: true })) {
+            const relative = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+            const absolute = path_1.default.join(dirAbs, entry.name);
+            const stats = (0, fs_1.lstatSync)(absolute);
+            if (stats.isDirectory()) {
+                walk(absolute, relative);
+                continue;
+            }
+            if (!stats.isFile()) {
+                fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'irregular-staged-entry' });
+            }
+            files.push({
+                path: relative,
+                sha256: (0, integrity_1.computeSha256Hex)((0, fs_1.readFileSync)(absolute)),
+                executable: (stats.mode & 0o111) !== 0,
+            });
+        }
+    };
+    walk(stagingDir, '');
+    return files;
+}
+/**
+ * Stage, verify and atomically publish one Skill install.
+ *
+ * Everything before the `renameSync` is undoable and is undone on any failure:
+ * the staging directory is removed and the destination is untouched. Everything
+ * after it is not, which is why the rename is the last thing that happens and
+ * why the caller records `FS_COMMITTED` the moment this returns.
+ *
+ * @throws SkillInstallError — the destination was not modified in every case.
+ */
+function applySkillInstall(input) {
+    if (!exports.SKILL_INSTALL_OPERATION_ID_PATTERN.test(input.operationId)) {
+        fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'operation-id' });
+    }
+    const rootPrefixes = input.rootPrefixes && input.rootPrefixes.length > 0
+        ? [...input.rootPrefixes]
+        : [constants_1.SKILL_INSTALL_ROOT_PREFIX];
+    // The payload is identical across roots: read and digest-verify it once, then
+    // stage the same bytes into each root (#1460).
+    const payload = input.snapshot.files.map((file) => {
+        const bytes = input.snapshot.readFile(file.path);
+        if (!(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)(bytes), file.sha256)) {
+            fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'snapshot-digest' });
+        }
+        return { relativePath: file.path, bytes, executable: file.executable };
+    });
+    const directories = directoriesFor(input.snapshot.files.map((f) => f.path), input.snapshot.directories);
+    // Every destination is proven safe and absent *before* the primary commits, so
+    // a secondary that is already blocked cannot leave a committed primary behind.
+    for (const prefix of rootPrefixes) {
+        const abs = resolveSkillInstallTargetFor(input.worktreePath, prefix, input.skillId);
+        assertAncestorsAreRealDirectories(input.worktreeRealPath, input.worktreePath, prefix);
+        const destination = inspectSkillDestination(abs);
+        if (destination.present) {
+            fail(destination.managed
+                ? exports.SkillInstallErrorCode.DESTINATION_EXISTS
+                : exports.SkillInstallErrorCode.DESTINATION_UNMANAGED, destination.version ? { version: destination.version } : undefined);
+        }
+    }
+    const committedRoots = [];
+    const pendingRoots = [];
+    for (let index = 0; index < rootPrefixes.length; index += 1) {
+        const prefix = rootPrefixes[index];
+        try {
+            stageAndCommitSkillRoot({
+                worktreePath: input.worktreePath,
+                worktreeRealPath: input.worktreeRealPath,
+                rootPrefix: prefix,
+                skillId: input.skillId,
+                operationId: input.operationId,
+                payload,
+                directories,
+                receiptBytes: input.receiptBytes,
+                plannedTreeHash: input.plannedTreeHash,
+            });
+            committedRoots.push((0, preview_diff_1.skillInstallRootFor)(prefix, input.skillId));
+        }
+        catch (error) {
+            // The primary rename is the commit point. A failure there published
+            // nothing, so it rolls back cleanly and is rethrown. A failure at a
+            // secondary root leaves the primary committed: the operation is
+            // *committed, reconciling*, and the remaining roots are handed to #1234.
+            if (index === 0)
+                throw error;
+            for (let rest = index; rest < rootPrefixes.length; rest += 1) {
+                pendingRoots.push((0, preview_diff_1.skillInstallRootFor)(rootPrefixes[rest], input.skillId));
+            }
+            break;
+        }
+    }
+    const installRoots = rootPrefixes.map((prefix) => (0, preview_diff_1.skillInstallRootFor)(prefix, input.skillId));
+    const installRootRel = installRoots[0];
+    const receiptSha256 = (0, integrity_1.computeSha256Hex)(input.receiptBytes);
+    return {
+        installRoot: installRootRel,
+        installRoots,
+        committedRoots,
+        pendingRoots,
+        reconciling: pendingRoots.length > 0,
+        receiptPath: `${installRootRel}/${install_plan_1.SKILL_RECEIPT_FILENAME}`,
+        receiptSha256,
+        receiptSize: input.receiptBytes.byteLength,
+        files: input.snapshot.files.map((file) => ({
+            path: file.path,
+            sha256: file.sha256,
+            size: file.size,
+            executable: file.executable,
+        })),
+        treeHash: input.plannedTreeHash,
+    };
+}
+/** Sorted set of directories a payload implies, plus any the package declared. */
+function directoriesFor(filePaths, declared = []) {
+    const directories = new Set(declared);
+    for (const filePath of filePaths) {
+        const parents = filePath.split('/').slice(0, -1);
+        let walked = '';
+        for (const segment of parents) {
+            walked = walked === '' ? segment : `${walked}/${segment}`;
+            directories.add(walked);
+        }
+    }
+    return [...directories].sort();
+}
+/**
+ * Stage the verified payload into one root and atomically publish it (#1460).
+ *
+ * The single-root commit #1235 built, lifted to take the root prefix as a
+ * parameter: staging lives under *that* root's reserved namespace so the rename
+ * stays on one filesystem, and every check — ancestor lstat walk, exclusive
+ * no-follow writes, tree-hash gate, destination-absent, same-filesystem — is
+ * applied per root. Throws {@link SkillInstallError} on any failure, having
+ * removed its own staging; the destination is untouched unless the rename ran.
+ */
+function stageAndCommitSkillRoot(input) {
+    const installRootAbs = resolveSkillInstallTargetFor(input.worktreePath, input.rootPrefix, input.skillId);
+    assertAncestorsAreRealDirectories(input.worktreeRealPath, input.worktreePath, input.rootPrefix);
+    const destinationBefore = inspectSkillDestination(installRootAbs);
+    if (destinationBefore.present) {
+        fail(destinationBefore.managed
+            ? exports.SkillInstallErrorCode.DESTINATION_EXISTS
+            : exports.SkillInstallErrorCode.DESTINATION_UNMANAGED, destinationBefore.version ? { version: destinationBefore.version } : undefined);
+    }
+    const stagingRoot = (0, operation_store_1.getSkillInstallStagingRoot)(input.worktreePath, input.rootPrefix);
+    makeDirectory(path_1.default.dirname(stagingRoot), 0o755, true);
+    makeDirectory(stagingRoot, exports.SKILL_INSTALL_DIR_MODE, true);
+    // Not recursive: a staging directory that already exists means another
+    // operation is using this ID, and silently adopting it would merge two writes.
+    const stagingDir = path_1.default.join(stagingRoot, input.operationId);
+    makeDirectory(stagingDir, exports.SKILL_INSTALL_DIR_MODE, false);
+    try {
+        for (const directory of input.directories) {
+            makeDirectory(path_1.default.join(stagingDir, directory), exports.SKILL_INSTALL_DIR_MODE, false);
+        }
+        for (const file of input.payload) {
+            // The execute bit comes from the reconciled inventory, which is also what
+            // the plan hashed — never from the archive header, which is attacker data.
+            writeSkillPayloadFile(path_1.default.join(stagingDir, file.relativePath), file.bytes, file.executable);
+        }
+        // The receipt is written last and from the plan's own bytes: rebuilding it
+        // here would make the file the user previewed and the file on disk two
+        // different artifacts that merely ought to agree.
+        writeSkillPayloadFile(path_1.default.join(stagingDir, install_plan_1.SKILL_RECEIPT_FILENAME), input.receiptBytes, false);
+        const staged = readStagedTree(stagingDir);
+        const treeHash = (0, preview_diff_1.computeSkillTreeHash)(staged);
+        if (treeHash !== input.plannedTreeHash) {
+            fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'tree-hash' });
+        }
+        assertSameFilesystem(stagingDir, path_1.default.dirname(installRootAbs));
+        // Re-checked immediately before the rename rather than only at entry: the
+        // exclusive lock keeps CommandMate out, but nothing keeps the user's own
+        // editor from creating this directory while the payload was being staged.
+        assertAncestorsAreRealDirectories(input.worktreeRealPath, input.worktreePath, input.rootPrefix);
+        const destinationNow = inspectSkillDestination(installRootAbs);
+        if (destinationNow.present) {
+            fail(destinationNow.managed
+                ? exports.SkillInstallErrorCode.DESTINATION_EXISTS
+                : exports.SkillInstallErrorCode.DESTINATION_UNMANAGED);
+        }
+        try {
+            (0, fs_1.renameSync)(stagingDir, installRootAbs);
+        }
+        catch {
+            fail(exports.SkillInstallErrorCode.COMMIT_FAILED, { reason: 'rename' });
+        }
+    }
+    catch (error) {
+        (0, fs_1.rmSync)(stagingDir, { recursive: true, force: true });
+        pruneStagingRoot(stagingRoot);
+        throw error;
+    }
+    pruneStagingRoot(stagingRoot);
+}
+/**
+ * Converge a committed install's secondary roots forward from the primary (#1460).
+ *
+ * The reconciliation primitive for a partial multi-root install: when the
+ * primary `.agents/skills` root committed but a secondary rename did not, this
+ * reads the primary's own on-disk payload — proven byte-for-byte against the
+ * receipt inventory — and atomically writes it into every declared root that is
+ * still absent. A root already present (the correct managed copy, or a user's
+ * conflict) is left untouched, so convergence is forward-only and never
+ * overwrites. Idempotent: a second call after a partial pass completes the rest.
+ *
+ * @returns repository-relative roots this call wrote
+ */
+function completeSecondarySkillInstallRoots(worktreePath, worktreeRealPath, skillId) {
+    const primaryAbs = resolveSkillInstallTarget(worktreePath, skillId);
+    const receiptBytes = (0, fs_1.readFileSync)(path_1.default.join(primaryAbs, install_plan_1.SKILL_RECEIPT_FILENAME));
+    const receipt = (0, install_plan_1.parseInstalledReceipt)(receiptBytes);
+    if (receipt === null) {
+        fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'primary-receipt-unreadable' });
+    }
+    // Read the primary payload from disk and prove it against the receipt before
+    // it is copied anywhere: a copy of a tampered primary must not propagate.
+    const payload = receipt.files.map((file) => {
+        const bytes = (0, fs_1.readFileSync)(path_1.default.join(primaryAbs, file.path));
+        if (!(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)(bytes), file.sha256)) {
+            fail(exports.SkillInstallErrorCode.PAYLOAD_MISMATCH, { reason: 'primary-file-digest' });
+        }
+        return { relativePath: file.path, bytes, executable: file.executable };
+    });
+    const directories = directoriesFor(receipt.files.map((file) => file.path));
+    const plannedTreeHash = (0, preview_diff_1.computeSkillTreeHash)([
+        ...receipt.files.map((file) => ({
+            path: file.path,
+            sha256: file.sha256,
+            executable: file.executable,
+        })),
+        { path: install_plan_1.SKILL_RECEIPT_FILENAME, sha256: (0, integrity_1.computeSha256Hex)(receiptBytes), executable: false },
+    ]);
+    const operationId = (0, crypto_1.randomBytes)(16).toString('hex');
+    const completed = [];
+    for (const rootRel of (0, install_plan_1.receiptInstallRoots)(receipt)) {
+        const prefix = rootRel.slice(0, Math.max(0, rootRel.length - skillId.length - 1));
+        const abs = resolveSkillInstallTargetFor(worktreePath, prefix, skillId);
+        // Present already: either the correct managed copy or a user conflict. Both
+        // are left alone — convergence only fills absent roots.
+        if (inspectSkillDestination(abs).present)
+            continue;
+        stageAndCommitSkillRoot({
+            worktreePath,
+            worktreeRealPath,
+            rootPrefix: prefix,
+            skillId,
+            operationId,
+            payload,
+            directories,
+            receiptBytes,
+            plannedTreeHash,
+        });
+        completed.push(rootRel);
+    }
+    return { completed };
+}
+/**
+ * Refuse to commit across a filesystem boundary.
+ *
+ * `rename(2)` is only atomic within one filesystem; across one it fails with
+ * EXDEV, and a caller that "helpfully" fell back to copy+delete would give up
+ * the single property the whole design rests on. Staging is placed inside the
+ * destination's own parent so this holds by construction — the check is here so
+ * a future change that moves staging elsewhere fails loudly.
+ */
+function assertSameFilesystem(stagingDir, destinationParent) {
+    let stagingDev;
+    let destinationDev;
+    try {
+        stagingDev = (0, fs_1.lstatSync)(stagingDir).dev;
+        destinationDev = (0, fs_1.lstatSync)(destinationParent).dev;
+    }
+    catch {
+        return fail(exports.SkillInstallErrorCode.STAGING_IO, { reason: 'stat-device' });
+    }
+    if (stagingDev !== destinationDev) {
+        fail(exports.SkillInstallErrorCode.CROSS_DEVICE);
+    }
+}
+/** Remove the staging root once it is empty, so it does not linger in a worktree. */
+function pruneStagingRoot(stagingRoot) {
+    try {
+        (0, fs_1.rmdirSync)(stagingRoot);
+    }
+    catch {
+        // Still in use by a concurrent operation, or already gone.
+    }
+}
+/**
+ * Drop staging directories left behind by a crashed process.
+ *
+ * Only entries whose name matches the operation-ID grammar are removed, so
+ * pointing this at a directory holding anything else cannot destroy content.
+ *
+ * @returns Number of staging directories removed
+ */
+function cleanupSkillInstallStaging(worktreePath) {
+    let removed = 0;
+    // Each install root has its own staging namespace (#1460); clean all of them.
+    for (const rootPrefix of constants_1.SKILL_INSTALL_ROOT_PREFIXES) {
+        const stagingRoot = (0, operation_store_1.getSkillInstallStagingRoot)(worktreePath, rootPrefix);
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(stagingRoot);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!exports.SKILL_INSTALL_OPERATION_ID_PATTERN.test(entry))
+                continue;
+            (0, fs_1.rmSync)(path_1.default.join(stagingRoot, entry), { recursive: true, force: true });
+            removed += 1;
+        }
+        pruneStagingRoot(stagingRoot);
+    }
+    return removed;
+}