pi-session-mcp 0.8.0 → 0.8.1

package/.pi-session-mcp-cli/doctor.js

@@ -6,7 +6,7 @@ import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
 import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
 import { readSkillBases, SkillBasesError } from "./skill-customize.js";
-import { readSkillTree, shippedSkillsDirectory } from "./skill-library.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory } from "./skill-library.js";
 const defaultFileSystem = { readFile, stat, access };
 const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
@@ -67,9 +67,10 @@ async function productionBuildInputMtimes(root) {
 }
 /**
  * Compares the shipped skills with the fingerprints recorded when the operator copied them.
- * Reads only the bases file and the shipped files; nothing is executed or changed.
+ * Reads only the bases file and the shipped files, takes no lock and writes nothing: the bases
+ * file is replaced atomically, so a read sees either the old or the new content.
  */
-async function skillOverrideChecks(overrideDirectory, shippedDirectory) {
+async function skillOverrideChecks(overrideDirectory, shippedDirectory, released) {
     if (overrideDirectory === undefined)
         return [];
     let bases;
@@ -90,9 +91,15 @@ async function skillOverrideChecks(overrideDirectory, shippedDirectory) {
         catch {
             continue;
         }
-        checks.push(fingerprint === base
-            ? ok("skill_override_outdated", `skill:${name}`)
-            : warning("skill_override_outdated", `skill:${name}`, `review the changed shipped skill, then run pi-session-mcp-setup --apply --customize-skill ${name}`));
+        const command = `pi-session-mcp-setup --apply --customize-skill ${name}`;
+        // A legacy base is meaningful only as the version 2 value of the released original it names.
+        const recorded = LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(base) ? releasedSkillFingerprint(name, base, released) : base;
+        if (recorded === undefined)
+            checks.push(warning("skill_override_outdated", `skill:${name}`, `the recorded base predates version 2 fingerprints and cannot be confirmed; review the shipped skill, then run ${command}`));
+        else
+            checks.push(recorded === fingerprint
+                ? ok("skill_override_outdated", `skill:${name}`)
+                : warning("skill_override_outdated", `skill:${name}`, `review the changed shipped skill, then run ${command}`));
     }
     return checks;
 }
@@ -260,7 +267,7 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config)
-        checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot)));
+        checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
     checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
     const hasError = checks.some((check) => check.severity === "error");

package/.pi-session-mcp-cli/override-lock.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSupportedFilesystem, currentSetupPlatform, isTrustedSystemBinary, openLockedDarwin } from "./setup-platform.js";
+/**
+ * The kernel lock that serializes every read-modify-write of the skill bases file across
+ * processes. It lives on a stable lock file, never on the bases file: that file is replaced by a
+ * rename, which would move the lock onto an unlinked inode. The lock file is never deleted, and a
+ * holder that dies releases the lock through the kernel.
+ */
+export const SKILL_BASES_LOCK_FILE = ".pi-session-mcp-bases.lock";
+export const DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS = 30_000;
+const MIN_LOCK_TIMEOUT_MS = 50;
+const MAX_LOCK_TIMEOUT_MS = 120_000;
+/** Exit status of `flock -E` when the lock stayed busy for the whole wait. */
+const FLOCK_BUSY_EXIT = 75;
+const FLOCK_CANDIDATES = ["/usr/bin/flock", "/bin/flock"];
+export class OverrideLockError extends Error {
+    code;
+    constructor(code) {
+        super("Skill override lock is not available");
+        this.code = code;
+        this.name = "OverrideLockError";
+    }
+}
+/**
+ * Takes the exclusive lock for one override directory, which must exist. Fails closed: an
+ * unsupported platform, a missing trusted `flock`, an unsupported filesystem, a link or non-file
+ * at the lock path and a descriptor that no longer names the path all end in
+ * `override_lock_unavailable`.
+ */
+export async function acquireOverrideLock(overrideDirectory, options = {}) {
+    const platform = currentSetupPlatform(options.platform);
+    if (!platform)
+        throw new OverrideLockError("override_lock_unavailable");
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(MIN_LOCK_TIMEOUT_MS, Math.min(options.timeoutMs, MAX_LOCK_TIMEOUT_MS)) : DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS;
+    const flockPath = platform === "linux" ? flockBinary(options) : undefined;
+    if (platform === "linux" && flockPath === undefined)
+        throw new OverrideLockError("override_lock_unavailable");
+    try {
+        await assertSupportedFilesystem(overrideDirectory, platform, options.readStatfs);
+    }
+    catch {
+        throw new OverrideLockError("override_lock_unavailable");
+    }
+    const lockPath = join(overrideDirectory, SKILL_BASES_LOCK_FILE);
+    let handle;
+    try {
+        // macOS takes the kernel lock at open time; on Linux the trusted flock locks this very
+        // open file description, so the lock outlives the flock process and ends with this descriptor.
+        handle = await openLockFile(lockPath, platform, timeoutMs, options.signal);
+        if (flockPath !== undefined)
+            await lockWithFlock(flockPath, handle.fd, timeoutMs, options.signal);
+        // The path may have been replaced while waiting: the lock only counts on the file it names.
+        const [descriptor, linked] = await Promise.all([handle.stat(), lstat(lockPath)]);
+        if (!descriptor.isFile() || !linked.isFile() || descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+            throw new OverrideLockError("override_lock_unavailable");
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw error instanceof OverrideLockError ? error : new OverrideLockError("override_lock_unavailable");
+    }
+    const held = handle;
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await held.close().catch(() => undefined);
+        },
+    };
+}
+function flockBinary(options) {
+    const trusted = options.isTrustedBinary ?? ((path) => isTrustedSystemBinary(path));
+    return (options.flockCandidates ?? FLOCK_CANDIDATES).find((candidate) => trusted(candidate));
+}
+async function openLockFile(lockPath, platform, timeoutMs, signal) {
+    try {
+        if (platform === "darwin")
+            return await openLockedDarwin(lockPath, { timeoutMs, ...(signal ? { signal } : {}) });
+        return await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        throw new OverrideLockError(error.message === "ownership_lock_busy" ? "override_lock_busy" : "override_lock_unavailable");
+    }
+}
+function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new OverrideLockError("override_lock_unavailable"));
+            return;
+        }
+        let locker;
+        try {
+            // flock parses fractional seconds with the locale's decimal separator, so only whole
+            // seconds go on the command line. The exact bound is the timer below, which stops flock.
+            const wholeSeconds = String(Math.max(1, Math.ceil(timeoutMs / 1_000)));
+            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), "-w", wholeSeconds, "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
+        }
+        catch {
+            reject(new OverrideLockError("override_lock_unavailable"));
+            return;
+        }
+        let expired = false;
+        const stop = () => { if (locker.pid !== undefined) {
+            try {
+                process.kill(-locker.pid, "SIGKILL");
+            }
+            catch { /* already gone */ }
+        } };
+        const cleanup = () => { clearTimeout(bound); signal?.removeEventListener("abort", stop); };
+        const bound = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+        signal?.addEventListener("abort", stop, { once: true });
+        locker.once("error", () => { cleanup(); reject(new OverrideLockError("override_lock_unavailable")); });
+        locker.once("close", (code) => {
+            cleanup();
+            if (code === 0)
+                resolve();
+            else
+                reject(new OverrideLockError(code === FLOCK_BUSY_EXIT || expired ? "override_lock_busy" : "override_lock_unavailable"));
+        });
+    });
+}

package/.pi-session-mcp-cli/setup-platform.js

@@ -0,0 +1,195 @@
+import { execFile } from "node:child_process";
+import { constants, readdirSync, readFileSync, statSync } from "node:fs";
+import { open, statfs } from "node:fs/promises";
+export function currentSetupPlatform(platform = process.platform) {
+    return platform === "linux" || platform === "darwin" ? platform : undefined;
+}
+/** A regular, root-owned executable that no group or other user can replace. */
+export function isTrustedSystemBinary(path, statFile = statSync) {
+    try {
+        const file = statFile(path);
+        return file.isFile() && file.uid === 0 && (file.mode & 0o022) === 0 && (file.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readLinuxProcessGroup(pid) {
+    const line = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
+    const close = line.lastIndexOf(") ");
+    const state = line[close + 2];
+    if (close < 3 || !state || !/^[A-Za-z]$/.test(state) || line[close + 3] !== " ")
+        throw new Error("process_stat_invalid");
+    const fields = line.slice(close + 4).trim().split(/\s+/);
+    const group = Number(fields[1]);
+    if (!Number.isSafeInteger(group) || group < 0)
+        throw new Error("process_group_invalid");
+    return { group, state };
+}
+function linuxGroupState(group) {
+    let entries;
+    try {
+        entries = readdirSync("/proc", { withFileTypes: true });
+    }
+    catch {
+        return "unknown";
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+            continue;
+        try {
+            const sample = readLinuxProcessGroup(Number(entry.name));
+            if (sample.group === group && sample.state !== "Z")
+                return "alive";
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return "unknown";
+        }
+    }
+    return "gone";
+}
+function linuxTableReadable(selfPid) {
+    let sawSelf = false;
+    try {
+        for (const entry of readdirSync("/proc", { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+                continue;
+            try {
+                const pid = Number(entry.name);
+                readLinuxProcessGroup(pid);
+                if (pid === selfPid)
+                    sawSelf = true;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return false;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return sawSelf;
+}
+export const DARWIN_PS_PATH = "/bin/ps";
+const PS_ARGUMENTS = ["-A", "-o", "pid=,pgid=,stat="];
+const PS_TIMEOUT_MS = 2_000;
+const PS_MAX_OUTPUT_BYTES = 1_048_576;
+/** Parses `ps -A -o pid=,pgid=,stat=`; any unexpected line rejects the whole sample. */
+export function parsePsTable(output) {
+    const body = output.endsWith("\n") ? output.slice(0, -1) : output;
+    if (body.length === 0)
+        return undefined;
+    const entries = [];
+    for (const line of body.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+        if (!match)
+            return undefined;
+        const pid = Number(match[1]);
+        const group = Number(match[2]);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(group))
+            return undefined;
+        entries.push({ pid, group, state: match[3] });
+    }
+    return entries;
+}
+function runDarwinPs() {
+    if (!isTrustedSystemBinary(DARWIN_PS_PATH))
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        try {
+            execFile(DARWIN_PS_PATH, [...PS_ARGUMENTS], { env: { LC_ALL: "C" }, timeout: PS_TIMEOUT_MS, maxBuffer: PS_MAX_OUTPUT_BYTES, encoding: "utf8" }, (error, stdout) => {
+                // A non-zero exit, timeout, output overflow or spawn failure is indeterminate.
+                resolve(error ? undefined : { exitCode: 0, stdout });
+            });
+        }
+        catch {
+            resolve(undefined);
+        }
+    });
+}
+export function createProcessTable(platform, dependencies = {}) {
+    const selfPid = dependencies.selfPid ?? process.pid;
+    if (platform === "linux") {
+        return { pollMs: 10, groupState: async (group) => linuxGroupState(group), readable: async () => linuxTableReadable(selfPid) };
+    }
+    const runPs = dependencies.runPs ?? runDarwinPs;
+    const scan = async () => {
+        const output = await runPs();
+        if (!output || output.exitCode !== 0)
+            return undefined;
+        const entries = parsePsTable(output.stdout);
+        // A sample without the caller cannot be a complete process table.
+        return entries?.some((entry) => entry.pid === selfPid) ? entries : undefined;
+    };
+    return {
+        pollMs: 50,
+        async groupState(group) {
+            const entries = await scan();
+            if (!entries)
+                return "unknown";
+            return entries.some((entry) => entry.group === group && !entry.state.startsWith("Z")) ? "alive" : "gone";
+        },
+        async readable() { return (await scan()) !== undefined; },
+    };
+}
+// Kernel flock and directory fsync semantics are accepted only on the local
+// Linux filesystems covered by the setup test matrix.
+const SUPPORTED_LINUX_FILESYSTEMS = new Set([
+    0xef53, // ext2/3/4
+    0x58465342, // XFS
+    0x9123683e, // Btrfs
+    0x01021994, // tmpfs
+    0x794c7630, // overlayfs
+    0x2fc12fc1, // ZFS
+    0xf2f52010, // F2FS
+    0x24051905, // UBIFS
+    0xca451a4e, // bcachefs
+]);
+export async function assertSupportedFilesystem(path, platform, readStatfs = (target) => statfs(target)) {
+    const filesystem = await readStatfs(path);
+    if (platform === "linux") {
+        if (!SUPPORTED_LINUX_FILESYSTEMS.has(filesystem.type))
+            throw new Error("ownership_filesystem_unsupported");
+        return;
+    }
+    // macOS assigns f_type dynamically, so the directory must share the type of
+    // `/`, the sealed APFS system volume on every macOS that Node.js 22 supports.
+    if (filesystem.type !== (await readStatfs("/")).type)
+        throw new Error("ownership_filesystem_unsupported");
+}
+/** From XNU `bsd/sys/fcntl.h`; Node's `fs.constants` does not export these. */
+export const DARWIN_O_NONBLOCK = 0x4;
+export const DARWIN_O_EXLOCK = 0x20;
+/**
+ * Opens the lock file with an exclusive lock on its open file description,
+ * which has flock(2) semantics on macOS. A busy lock is retried until the
+ * acquisition bound; a failed attempt holds no descriptor.
+ */
+export async function openLockedDarwin(path, options) {
+    const openFile = options.openFile ?? ((target, flags, mode) => open(target, flags, mode));
+    const flags = constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW | DARWIN_O_EXLOCK | DARWIN_O_NONBLOCK;
+    const boundMs = Number.isFinite(options.timeoutMs) ? Math.max(1_000, Math.min(options.timeoutMs, 120_000)) : 120_000;
+    const deadline = Date.now() + boundMs;
+    const retryMs = options.retryMs ?? 50;
+    while (true) {
+        if (options.signal?.aborted)
+            throw new Error("operation_aborted");
+        try {
+            return await openFile(path, flags, 0o600);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EAGAIN" && code !== "EWOULDBLOCK")
+                throw new Error("ownership_lock_unavailable");
+        }
+        if (Date.now() >= deadline)
+            throw new Error("ownership_lock_busy");
+        await new Promise((resolve) => {
+            const done = () => { clearTimeout(timer); options.signal?.removeEventListener("abort", done); resolve(); };
+            const timer = setTimeout(done, retryMs);
+            options.signal?.addEventListener("abort", done, { once: true });
+        });
+    }
+}

package/.pi-session-mcp-cli/skill-customize.js

@@ -1,18 +1,24 @@
 import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, rename, rm, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
 import { result } from "./setup-result.js";
-import { readSkillTree, shippedSkillsDirectory, SKILL_NAME_PATTERN, SkillTreeError, skillOverrideDirectory } from "./skill-library.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory, SKILL_NAME_PATTERN, SKILL_TREE_FINGERPRINT_PATTERN, SkillTreeError, skillOverrideDirectory, } from "./skill-library.js";
 /**
  * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
  * starting point, and records the shipped fingerprint it was based on. The operator's files are
  * never overwritten or edited; a changed original is only reported and acknowledged by moving
  * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ *
+ * Applying is a cross-process transaction: everything from reading the bases file to replacing it
+ * runs under the kernel lock of `override-lock.ts`, so two runs for different skills cannot lose
+ * each other's base. A dry run takes no lock and writes nothing.
  */
 export const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
 export const MAX_SKILL_BASES_BYTES = 64 * 1024;
-const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+/** Written by this version; version 1 (0.8.0) holds only legacy fingerprints and is still read. */
+const BASES_SCHEMA_VERSION = 2;
 export class SkillBasesError extends Error {
     constructor() {
         super("Skill bases file is not usable");
@@ -46,13 +52,17 @@ export async function readSkillBases(overrideDirectory) {
     catch {
         throw new SkillBasesError();
     }
-    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion" || parsed.schemaVersion !== 1)
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion")
+        throw new SkillBasesError();
+    const version = parsed.schemaVersion;
+    if (version !== 1 && version !== BASES_SCHEMA_VERSION)
         throw new SkillBasesError();
     const bases = parsed.bases;
     if (!isPlainObject(bases))
         throw new SkillBasesError();
     const entries = Object.entries(bases);
-    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && typeof value === "string" && FINGERPRINT_PATTERN.test(value)))
+    const validValue = (value) => typeof value === "string" && (LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) || (version === BASES_SCHEMA_VERSION && SKILL_TREE_FINGERPRINT_PATTERN.test(value)));
+    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && validValue(value)))
         throw new SkillBasesError();
     return Object.freeze(Object.fromEntries(entries));
 }
@@ -62,10 +72,25 @@ function isPlainObject(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-/** Atomic replacement: a private temporary file in the same directory, then a rename. */
-async function writeSkillBases(overrideDirectory, bases) {
-    const sorted = Object.fromEntries(Object.entries(bases).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
-    const content = Buffer.from(`${JSON.stringify({ schemaVersion: 1, bases: sorted })}\n`, "utf8");
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Atomic replacement: a private temporary file in the same directory, fsynced, then a rename and a
+ * directory fsync. Every provable legacy entry is migrated to its version 2 value on the way; an
+ * entry that no released tree names stays verbatim. A failure before the rename leaves the
+ * previous file untouched.
+ */
+async function writeSkillBases(overrideDirectory, bases, released, beforeRename) {
+    const migrated = Object.entries(bases).map(([name, value]) => [name, LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) ? releasedSkillFingerprint(name, value, released) ?? value : value]);
+    const sorted = Object.fromEntries(migrated.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+    const content = Buffer.from(`${JSON.stringify({ schemaVersion: BASES_SCHEMA_VERSION, bases: sorted })}\n`, "utf8");
     if (content.length > MAX_SKILL_BASES_BYTES)
         throw new SkillBasesError();
     const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
@@ -78,12 +103,14 @@ async function writeSkillBases(overrideDirectory, bases) {
         finally {
             await handle.close();
         }
+        await beforeRename?.();
         await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
     }
     catch (error) {
         await unlink(temporary).catch(() => undefined);
         throw error;
     }
+    await syncDirectory(overrideDirectory);
 }
 function isMissing(error) {
     return typeof error === "object" && error !== null && error.code === "ENOENT";
@@ -96,7 +123,40 @@ function report(request, status, code) {
     // A planned change reports `planned` overall, like a registration dry-run.
     return result(request.apply ? "apply" : "dry-run", [finding], status === "planned" ? "planned" : undefined);
 }
-export async function customizeSkill(request) {
+const OUTDATED = Object.freeze({ kind: "record", planned: "skill_override_outdated", applied: "skill_base_updated" });
+/** Pure with respect to the library: reads the override tree, never changes anything. */
+async function decide(name, overridePath, shipped, bases, released) {
+    try {
+        if (!(await lstat(overridePath)).isDirectory())
+            return { kind: "failed", code: "skill_override_invalid" };
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return { kind: "copy", planned: "skill_customize_planned", applied: "skill_customized" };
+    }
+    let override;
+    try {
+        override = await readSkillTree(overridePath);
+    }
+    catch (error) {
+        if (error instanceof SkillTreeError)
+            return { kind: "failed", code: "skill_override_invalid" };
+        throw error;
+    }
+    const base = Object.hasOwn(bases, name) ? bases[name] : undefined;
+    // Without a base an identical override is a customization whose bases commit failed earlier.
+    if (base === undefined)
+        return override.fingerprint === shipped.fingerprint ? { kind: "record", planned: "skill_customize_planned", applied: "skill_customized" } : OUTDATED;
+    if (SKILL_TREE_FINGERPRINT_PATTERN.test(base))
+        return base === shipped.fingerprint ? { kind: "current" } : OUTDATED;
+    // A legacy base only names a released original when a trusted reference tree has that value.
+    const original = releasedSkillFingerprint(name, base, released);
+    if (original === undefined)
+        return { kind: "record", planned: "skill_base_unverified", applied: "skill_base_updated" };
+    return original === shipped.fingerprint ? { kind: "record", planned: "skill_base_migration_planned", applied: "skill_base_migrated" } : OUTDATED;
+}
+export async function customizeSkill(request, dependencies = {}) {
     const done = (status, code) => report(request, status, code);
     if (!SKILL_NAME_PATTERN.test(request.name))
         return done("failed", "skill_not_shipped");
@@ -112,69 +172,94 @@ export async function customizeSkill(request) {
             return done("failed", "skill_customize_failed");
         }
         const overrideDirectory = skillOverrideDirectory(request.configPath);
-        let bases;
-        try {
-            bases = await readSkillBases(overrideDirectory);
-        }
-        catch (error) {
-            if (error instanceof SkillBasesError)
+        const overridePath = join(overrideDirectory, request.name);
+        const read = async () => {
+            try {
+                return await readSkillBases(overrideDirectory);
+            }
+            catch (error) {
+                if (error instanceof SkillBasesError)
+                    return undefined;
+                throw error;
+            }
+        };
+        if (!request.apply) {
+            // No lock and no write: the report is a snapshot of what an apply would decide.
+            const bases = await read();
+            if (bases === undefined)
                 return done("failed", "skill_bases_corrupt");
-            throw error;
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            return decision.kind === "current" ? done("unchanged", "skill_override_current") : done("planned", decision.planned);
         }
-        const overridePath = join(overrideDirectory, request.name);
-        let exists = true;
+        await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+        let lock;
         try {
-            const info = await lstat(overridePath);
-            if (!info.isDirectory())
-                return done("failed", "skill_override_invalid");
+            lock = await acquireOverrideLock(overrideDirectory, dependencies.lock);
         }
         catch (error) {
-            if (!isMissing(error))
-                throw error;
-            exists = false;
-        }
-        if (!exists) {
-            if (!request.apply)
-                return done("planned", "skill_customize_planned");
-            await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
-            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
-            return done("ok", "skill_customized");
+            if (error instanceof OverrideLockError)
+                return done("failed", error.code === "override_lock_busy" ? "skill_customize_lock_busy" : "skill_customize_lock_unavailable");
+            throw error;
         }
         try {
-            await readSkillTree(overridePath);
+            await dependencies.afterLock?.();
+            // Read only now: a snapshot from before the lock may miss a base another run just wrote.
+            const bases = await read();
+            if (bases === undefined)
+                return done("failed", "skill_bases_corrupt");
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            if (decision.kind === "current")
+                return done("unchanged", "skill_override_current");
+            if (decision.kind === "copy")
+                await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
+            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint }, dependencies.released, dependencies.beforeBasesRename);
+            return done("ok", decision.applied);
         }
-        catch (error) {
-            if (error instanceof SkillTreeError)
-                return done("failed", "skill_override_invalid");
-            throw error;
+        finally {
+            await lock.release();
         }
-        if (bases[request.name] === shipped.fingerprint)
-            return done("unchanged", "skill_override_current");
-        if (!request.apply)
-            return done("planned", "skill_override_outdated");
-        // Only the recorded base moves: it acknowledges that the operator reviewed the changed original.
-        await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
-        return done("ok", "skill_base_updated");
     }
     catch {
         return done("failed", "skill_customize_failed");
     }
 }
 async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
-    await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
     const temporary = join(overrideDirectory, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
     try {
         await mkdir(temporary, { mode: 0o755 });
         for (const file of files) {
             const destination = join(temporary, ...file.path.split("/"));
             await mkdir(dirname(destination), { recursive: true });
-            await writeFile(destination, file.bytes, { flag: "wx", mode: 0o644 });
+            const handle = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+            try {
+                await handle.writeFile(file.bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        // Every directory entry of the temporary tree is durable before the rename and the bases commit.
+        const directories = new Set([temporary]);
+        for (const file of files) {
+            let cursor = dirname(join(temporary, ...file.path.split("/")));
+            while (cursor !== temporary) {
+                directories.add(cursor);
+                cursor = dirname(cursor);
+            }
         }
+        for (const directory of [...directories].sort((left, right) => right.length - left.length))
+            await syncDirectory(directory);
         // The override must not appear while the copy runs, and an operator's directory is never replaced.
         if (await lstat(overridePath).then(() => true, (error) => { if (isMissing(error))
             return false; throw error; }))
             throw new Error("override appeared");
         await rename(temporary, overridePath);
+        await syncDirectory(overrideDirectory);
     }
     catch (error) {
         await rm(temporary, { recursive: true, force: true }).catch(() => undefined);