pi-session-mcp 0.7.1 → 0.8.1

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

@@ -0,0 +1,268 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+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 { 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;
+/** 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");
+        this.name = "SkillBasesError";
+    }
+}
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export async function readSkillBases(overrideDirectory) {
+    const path = join(overrideDirectory, SKILL_BASES_FILE);
+    let text;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        const bytes = await readFile(path);
+        if (bytes.length > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            throw error;
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return Object.freeze({});
+        throw new SkillBasesError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillBasesError();
+    }
+    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);
+    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));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+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`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        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";
+}
+function report(request, status, code) {
+    // The name is echoed only when it is a valid skill name, so arbitrary input never reaches a report.
+    const alias = SKILL_NAME_PATTERN.test(request.name) ? request.name : "invalid";
+    const target = { client: "skills", scope: "override", alias };
+    const finding = { target, 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);
+}
+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");
+    try {
+        const shippedDirectory = join(shippedSkillsDirectory(request.packageRoot), request.name);
+        let shipped;
+        try {
+            shipped = await readSkillTree(shippedDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError && error.code === "skill_tree_missing")
+                return done("failed", "skill_not_shipped");
+            return done("failed", "skill_customize_failed");
+        }
+        const overrideDirectory = skillOverrideDirectory(request.configPath);
+        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");
+            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);
+        }
+        await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+        let lock;
+        try {
+            lock = await acquireOverrideLock(overrideDirectory, dependencies.lock);
+        }
+        catch (error) {
+            if (error instanceof OverrideLockError)
+                return done("failed", error.code === "override_lock_busy" ? "skill_customize_lock_busy" : "skill_customize_lock_unavailable");
+            throw error;
+        }
+        try {
+            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);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    catch {
+        return done("failed", "skill_customize_failed");
+    }
+}
+async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
+    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 });
+            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);
+        throw error;
+    }
+}

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

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export const SKILL_NAME_PATTERN = /^(?=.{1,64}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export const CONTROLLER_SKILLS = Object.freeze(["pi-session-orchestration"]);
+export const MAX_SKILL_TREE_FILES = 32;
+export const MAX_SKILL_TREE_BYTES = 1024 * 1024;
+const MAX_SKILL_TREE_DEPTH = 8;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+export function shippedSkillsDirectory(packageRoot = PACKAGE_ROOT) {
+    return join(packageRoot, "skills");
+}
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export function skillOverrideDirectory(configPath) {
+    return join(dirname(resolve(configPath)), "skills");
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export function resolveLibrarySkill(name, roots) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return undefined;
+    const override = join(roots.overrideDirectory, name);
+    if (isRegularFile(join(override, "SKILL.md")))
+        return Object.freeze({ name, source: "override", directory: override });
+    const shipped = join(shippedSkillsDirectory(roots.packageRoot), name);
+    if (isRegularFile(join(shipped, "SKILL.md")))
+        return Object.freeze({ name, source: "shipped", directory: shipped });
+    return undefined;
+}
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export function builtinSkillPath(name, roots) {
+    const skill = resolveLibrarySkill(name, roots);
+    return join(skill?.directory ?? join(shippedSkillsDirectory(roots.packageRoot), name), "SKILL.md");
+}
+export class SkillTreeError extends Error {
+    code;
+    constructor(code) {
+        super("Skill directory is not usable");
+        this.code = code;
+        this.name = "SkillTreeError";
+    }
+}
+/** A version 2 skill tree fingerprint as it is stored. */
+export const SKILL_TREE_FINGERPRINT_PATTERN = /^v2:[0-9a-f]{64}$/;
+/** A version 1 fingerprint as 0.8.0 stored it: bare SHA-256 hex. */
+export const LEGACY_SKILL_TREE_FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const FINGERPRINT_DOMAIN = "pi-session-mcp skill tree v2\n";
+function uint32(value) {
+    const bytes = Buffer.alloc(4);
+    bytes.writeUInt32BE(value);
+    return bytes;
+}
+function uint64(value) {
+    const bytes = Buffer.alloc(8);
+    bytes.writeBigUInt64BE(BigInt(value));
+    return bytes;
+}
+/**
+ * Version 2: a domain and version tag, the file count, then per file in byte order of the path
+ * the length-prefixed UTF-8 path and the length-prefixed content. Every field has an explicit
+ * length, so two different trees never share an encoding.
+ */
+export function skillTreeFingerprint(files) {
+    const entries = files.map((file) => ({ path: Buffer.from(file.path, "utf8"), bytes: file.bytes }))
+        .sort((left, right) => Buffer.compare(left.path, right.path));
+    const hash = createHash("sha256").update(FINGERPRINT_DOMAIN, "utf8").update(uint32(entries.length));
+    entries.forEach((entry, index) => {
+        if (index > 0 && Buffer.compare(entries[index - 1].path, entry.path) === 0)
+            throw new SkillTreeError("skill_tree_invalid");
+        hash.update(uint32(entry.path.length)).update(entry.path).update(uint64(entry.bytes.length)).update(entry.bytes);
+    });
+    return `v2:${hash.digest("hex")}`;
+}
+/**
+ * Version 1, as 0.8.0 computed it: `path NUL content NUL` per file in reading order. File
+ * content may contain NUL bytes, so two different trees can share this value.
+ */
+export function legacySkillTreeFingerprint(files) {
+    const hash = createHash("sha256");
+    for (const file of files)
+        hash.update(file.path).update("\0").update(file.bytes).update("\0");
+    return hash.digest("hex");
+}
+/**
+ * The shipped skills of every release that recorded version 1 fingerprints (0.8.0 only), as
+ * trusted references for recognizing such records. Computed from the `v0.8.0` tag and checked
+ * against the published npm package.
+ */
+export const RELEASED_SKILL_TREES = Object.freeze([
+    Object.freeze({ name: "pi-session-orchestration", release: "0.8.0", legacyFingerprint: "e2a72b558ea14748a4badd0058ff65b8731cc125033a666706b103842784673a", fingerprint: "v2:39edc4c4783dec7f90345b22844a17e5e48b465722bb0f1b20059d6ee51e1523" }),
+    Object.freeze({ name: "pi-session-implementation", release: "0.8.0", legacyFingerprint: "5f719b44da266d3f66dd5bf3c18f3e3e04ca7df357e2fe2eedbf0409e6c1bf64", fingerprint: "v2:f8ce75eff83a5c952f6ca51c04e1e8025cb7c2c558c30d692f291a3f6594eb12" }),
+    Object.freeze({ name: "pi-session-review", release: "0.8.0", legacyFingerprint: "8cf58ccb8d473a3eedf12ce6b902b1e91dd9e2fef83ad110c4d8e2e6164cb257", fingerprint: "v2:610c0b4829eeb1ce6c9b2000ad73f8e88ca230707eef7f7b1708a80767952bf0" }),
+]);
+/**
+ * Whether a version 1 fingerprint from a record proves that `candidate` is the tree it names:
+ * a trusted reference, a released shipped tree of this name or one of `references` (such as
+ * the current library tree), has exactly this version 1 fingerprint and is byte-identical to
+ * `candidate` by its version 2 fingerprint. The version 1 fingerprint alone never suffices.
+ */
+export function provesLegacyFingerprint(name, legacyFingerprint, candidate, references = [], released = RELEASED_SKILL_TREES) {
+    if (!LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(legacyFingerprint) || !SKILL_TREE_FINGERPRINT_PATTERN.test(candidate.fingerprint))
+        return false;
+    const trusted = [...released.filter((tree) => tree.name === name), ...references];
+    return trusted.some((tree) => tree.legacyFingerprint === legacyFingerprint && tree.fingerprint === candidate.fingerprint);
+}
+/**
+ * The version 2 fingerprint of the released shipped skill that a version 1 fingerprint names,
+ * or undefined. Only released trees qualify: the current shipped tree could share a version 1
+ * fingerprint with an older original without being that original.
+ */
+export function releasedSkillFingerprint(name, legacyFingerprint, released = RELEASED_SKILL_TREES) {
+    return released.find((tree) => tree.name === name && tree.legacyFingerprint === legacyFingerprint)?.fingerprint;
+}
+/**
+ * Reads the regular files below a skill directory in a stable order. Entries whose name starts
+ * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export async function readSkillTree(directory, options = {}) {
+    let root;
+    try {
+        root = await realpath(directory);
+    }
+    catch {
+        throw new SkillTreeError("skill_tree_missing");
+    }
+    const files = [];
+    let bytes = 0;
+    const visit = async (current, prefix, depth) => {
+        if (depth > MAX_SKILL_TREE_DEPTH)
+            throw new SkillTreeError("skill_tree_invalid");
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            throw new SkillTreeError("skill_tree_invalid");
+        }
+        for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+            if (entry.name.startsWith(".")) {
+                if (options.hidden === "reject")
+                    throw new SkillTreeError("skill_tree_invalid");
+                continue;
+            }
+            const path = join(current, entry.name);
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                await visit(path, relativePath, depth + 1);
+                continue;
+            }
+            if (!info.isFile())
+                throw new SkillTreeError("skill_tree_invalid");
+            if (files.length + 1 > MAX_SKILL_TREE_FILES || bytes + info.size > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            const content = await readFile(path);
+            // Counted as read, so a file that grew after lstat cannot pass the limit.
+            bytes += content.length;
+            if (bytes > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            files.push(Object.freeze({ path: relativePath, bytes: content }));
+        }
+    };
+    await visit(root, "", 0);
+    if (!files.some((file) => file.path === "SKILL.md"))
+        throw new SkillTreeError("skill_tree_missing");
+    return Object.freeze({ files: Object.freeze(files), fingerprint: skillTreeFingerprint(files), legacyFingerprint: legacySkillTreeFingerprint(files) });
+}

package/CHANGELOG.md

@@ -2,6 +2,182 @@
 
 ## Unreleased
 
+## 0.8.1 — 2026-10-12
+
+- `updatedAt` of a running turn now follows public SDK activity. It is the time
+  of the last observed assistant message start, update or end and tool
+  execution start, update or end of that turn, and freezes at the terminal
+  transition. Before, it advanced only after a completed tool execution or a
+  completed assistant message, so a turn of an extension provider with its own
+  agent loop, such as `pi-cursor-sdk`, kept `updatedAt == startedAt` while it
+  streamed. Streaming is activity, not evidence of finished or useful work, and
+  work without a public event stays invisible, so an unchanged `updatedAt` is
+  still no proof of a hang. No event content is stored or projected, and the
+  answer still comes only from the final assistant message. See [tool
+  contracts](docs/tool-contracts.md). Issue #47.
+- Skill tree fingerprints are now version 2 (`v2:` and 64 hex digits), an
+  unambiguous encoding with explicit lengths. Version 1 of 0.8.0 hashed
+  `path NUL content NUL` and could give two different trees the same value,
+  because content may contain NUL bytes. A version 1 value never proves
+  identity alone: it counts only when a trusted reference (the shipped skills of
+  0.8.0, or for setup's installed copies the current library tree) has that
+  value and is byte-identical to the tree in question. Issue #51.
+- Skill customization is now serialized across processes. `--apply
+  --customize-skill` takes an exclusive kernel lock on
+  `<override dir>/.pi-session-mcp-bases.lock`, re-reads the bases file under the
+  lock and replaces it atomically, so two runs for different skills no longer
+  lose a base. The wait is bounded at 30 seconds. New codes:
+  `skill_customize_lock_busy` and `skill_customize_lock_unavailable`. The
+  dry-run takes no lock and writes nothing. The bases file is now schema version
+  2; version 1 files are still read, and every write migrates each legacy value
+  that names a released 0.8.0 shipped skill. New codes for a legacy base:
+  `skill_base_migration_planned` and `skill_base_migrated` (it names the current
+  shipped skill), and `skill_base_unverified` (it names no released skill; the
+  Doctor warning `skill_override_outdated` says that the base cannot be
+  confirmed). `skill_customize_planned` and `skill_customized` now also complete
+  a customization whose bases commit failed. See [Pi
+  skills](docs/skills.md#concurrent-runs-and-the-override-lock). Issue #50.
+- Setup's installed skill copies. Ownership records of skill copies now hold
+  version 2 fingerprints. A record that 0.8.0 wrote is migrated only when a
+  trusted reference proves the copy's exact bytes; otherwise dry-run, apply,
+  remove and rollback report the new code `skill_legacy_unverified` and change
+  neither the copy nor the record. Updates now name their intermediate
+  directories after the pending record's transaction id
+  (`.pi-session-mcp-<skill>-<transactionId>.staging`, `.backup`, `.trash`), and
+  `--apply`, `--remove` and `--rollback` first settle an interrupted update.
+  Anything modified or foreign stays and is reported as the new code
+  `skill_recovery_retained`. A failed update leaves its staging directory until
+  the next run settles it. Directories of 0.8.0 updates are never searched for
+  or deleted. When `--apply` settled an interrupted update and needs no further
+  update it reports the new code `skill_recovered`, and a dry-run of a pending
+  update reports `skill_recovery_planned`. Issues #51 and #52.
+- Upgrading from 0.8.0: run `pi-session-mcp-setup` as a dry-run and then with
+  `--apply`. Unchanged copies of the 0.8.0 controller skill are proven against
+  the 0.8.0 table and migrated; others stay and report
+  `skill_legacy_unverified`. Doctor resolves 0.8.0 bases against the same table,
+  and the next `--apply --customize-skill` rewrites the bases file as version 2.
+  0.8.0 rejects the new formats as corrupt (the bases file, and the whole
+  ownership file once it holds a version 2 skill record), so it never acts on
+  them. See [Upgrade from 0.8.0](docs/skills.md#upgrade-from-080) and
+  [Downgrade](docs/skills.md#downgrade).
+- The orchestration skill now says that a successful `pi_session_start` does not
+  prove that the provider accepts requests, asks for a bounded observation and
+  cleanup budget after `abort_timeout`, separates start errors that need the
+  operator from ones that can be transient, and describes `updatedAt` as the
+  last observed public SDK activity. `docs/acceptance.md` records the v0.8.0
+  post-release acceptance and names the method limits of earlier multi-session
+  records. Issue #54.
+- The multi-session acceptance harness (`scripts/multi-session-acceptance.mjs`,
+  not in the npm package) now ends a run within validated time bounds and
+  terminates only processes that provably belong to it (PID and start time). It
+  checks scope against a baseline stored outside the worker workspace (working
+  tree, index and HEAD, so committed changes count) and adds its own business
+  checks to the fixture tests, with Git pinned to the fixture and hooks,
+  `fsmonitor` and replace objects switched off. It binds the build, the
+  controller and worker skills, the override directory, the configuration, the
+  fixture baselines, itself and the operator's own `pi-session-orchestration`
+  copies in `~/.claude/skills` and `~/.agents/skills` at `prepare` and rechecks
+  them before launch and after the run; a Codex run is refused while the home
+  copy differs from the candidate's skill. It records each launch before the
+  controller starts, writes each original result once, records reanalyses
+  separately, and lists every launch in the evidence, marking one without a
+  result. A failed analysis, or a signal to the harness during it, is recorded
+  as `analysisFailed`, never passes, still terminates the run's processes and
+  makes the CLI exit with 1. `prepare --with-extensions` copies the exact
+  extension allowlist of a selected profile for extension providers such as
+  Cursor. Each session reports whether a polled running turn showed
+  `updatedAt` beyond `startedAt`. See
+  [Acceptance](docs/acceptance.md#multi-session-skill-acceptance). Issue #53.
+- A release now travels in the pull request of the change it ships, with the
+  version, the changelog heading and the pre-release acceptance record; records
+  that need the published release follow with the next change. See
+  [Releasing](docs/releasing.md#prepare-a-release).
+
+## 0.8.0 — 2026-10-12
+
+This is a minor release because the public contract changes, as ADR 0003
+requires: the `skills` field of each execution profile in
+`pi_capabilities_get` and the new error code `skill_load_failed`.
+
+- Execution profiles can select Pi skills. An optional top-level
+  `skillCatalog` maps a skill alias to the path of one `SKILL.md` file (or to
+  `builtin:<name>`, see below), and an
+  optional `skills` list in a profile selects catalog aliases. MCP callers still
+  choose only workspace and profile aliases; no tool takes a skill. A session
+  loads exactly the selected skills and validates them at start; a missing,
+  unreadable, oversized or invalid skill, a duplicate Pi skill name, two aliases
+  on one file, or an explicit-only skill (`disable-model-invocation: true`)
+  fails the start with the new error `skill_load_failed`. Every execution
+  profile in `pi_capabilities_get` gains `skills`, the selected catalog aliases
+  (`[]` when none). Doctor gains `skill_missing`, `skill_unreadable` and
+  `skill_duplicate`. Skill file contents are not snapshotted; do not change
+  them while sessions that use them are active. See [Pi
+  skills](docs/skills.md) and [ADR 0007](docs/adr/0007-profile-skill-selection.md).
+  Issue #46.
+- Compatibility change: with Pi SDK 1.1.0, skills that an allowlisted
+  extension package bundles reached a session although `noSkills` was set. An
+  extension allowlist alone now makes none of its skills available. A profile
+  that relied on them needs a catalog entry with the absolute path of the
+  package's `SKILL.md` and a `skills` selection; see the migration section of
+  [Pi skills](docs/skills.md).
+- Prompt templates and themes that extension packages ship are now closed
+  through the SDK's public overrides as well. They were already never expanded
+  for MCP prompts.
+- The package ships three skills under `skills/`: `pi-session-orchestration`
+  for the controlling Claude Code or Codex agent, and `pi-session-implementation`
+  and `pi-session-review` for Pi workers. The example configuration registers
+  the two worker skills with `builtin:` references, so a copied example needs
+  no path edits for skills.
+- Skill library and `builtin:`. A `skillCatalog` value `builtin:<name>` names a
+  skill of the library: the operator's override
+  `<configuration directory>/skills/<name>/SKILL.md` if it exists, else the
+  skill shipped in the package. Resolution happens when the configuration
+  loads, so adding or removing an override needs a restart. A name that matches
+  neither keeps the shipped location, so Doctor reports `skill_missing` and a
+  session start fails with `skill_load_failed`. A malformed `builtin:` name makes
+  the configuration invalid.
+- `pi-session-mcp-setup --customize-skill <name>` (a dry-run; `--apply` writes)
+  copies a shipped skill into the override directory as a starting point and
+  records the shipped fingerprint in `.pi-session-mcp-bases.json`. It never
+  overwrites an existing override. Findings use the target
+  `skills/override/<name>` and the new codes `skill_customize_planned`,
+  `skill_customized`, `skill_override_current`, `skill_override_outdated`,
+  `skill_base_updated`, `skill_not_shipped`, `skill_bases_corrupt`,
+  `skill_override_invalid` and `skill_customize_failed`. After a package
+  update changed a shipped skill, `--apply --customize-skill <name>` moves only
+  the recorded base once you reviewed the change; it never touches your files.
+  A new skill needs no command: create `<override dir>/<name>/SKILL.md` and
+  reference it as `builtin:<name>`.
+- `pi-session-mcp-setup --apply` now also installs the controller skill
+  `pi-session-orchestration` for each target, after the registration, as a real
+  copy of the effective skill (override, else shipped): Codex `~/.agents/skills/`,
+  Claude Code `user` and `local` `~/.claude/skills/` (one shared directory),
+  Claude Code `project` `<project>/.claude/skills/`. The ownership record holds
+  only a content fingerprint. Setup never replaces or deletes a modified copy, a
+  foreign skill of the same name, hidden operator files inside the copy, or a
+  linked or non-directory entry (`skill_divergent`); a link to exactly the
+  effective skill is accepted as the operator's own (`skill_linked`). Inside a
+  project setup never follows a link, and a project copy is bound to its
+  project. A setup result has a second finding per target with the alias
+  `pi-session-orchestration` whenever the skill step runs (not for an apply
+  that the plan refuses or a registration that failed); the new codes are `skill_absent`,
+  `skill_equivalent`, `skill_linked`, `skill_update_planned`, `skill_source_invalid`,
+  `skill_installed`, `skill_already_equivalent`, `skill_updated`,
+  `skill_install_failed`, `skill_verified`, `skill_missing`,
+  `skill_not_equivalent`, `skill_removed`, `skill_kept_shared`,
+  `skill_not_owned` and `skill_divergent`. A divergent skill does not block the
+  registration but makes the overall status `failed`. `--remove` and
+  `--rollback` remove an unmodified copy, and a retry still cleans up a skill
+  that setup owns after the registration is gone. Manual symlinking of the
+  skill is no longer needed.
+- Doctor gains the warning `skill_override_outdated` (subject `skill:<name>`,
+  or `skill:bases` for a corrupt bases file) when a shipped skill changed since
+  the operator copied it.
+- Maintainers get `scripts/multi-session-acceptance.mjs`, a live check in which
+  a real Claude Code or Codex controller drives two concurrent Pi sessions
+  with selected skills, including a targeted abort. It is not part of the npm
+  package; see [acceptance](docs/acceptance.md#multi-session-skill-acceptance).
+
 ## 0.7.1 — 2026-10-11
 
 The public MCP contract is unchanged.