pi-session-mcp 0.7.1 → 0.8.1

package/README.md

@@ -18,6 +18,7 @@ Reasons to do that:
 - **Follow-up turns keep their context.** A session stays open across prompts, so a follow-up question does not pay for the same exploration twice.
 - **You set the limits, not the agent.** The client can only pick from the workspaces and profiles in your configuration file. It cannot name a directory, a model, a provider or a permission level, and the default profile is read-only.
 - **Exactly the extra tools a task needs.** A profile can grant individual tools of local stdio MCP servers to its sessions, and nothing else from those servers.
+- **Role instructions you control.** A profile can select Pi skills from a catalog in your configuration, such as the implementation and review skills this package ships, or your own versions of them. The client cannot choose skills. The package also ships an orchestration skill for the controlling agent, which `setup` installs into Claude Code and Codex.
 - **Predictable to automate.** Sessions and turns have a small set of states and stable error codes. Results contain no paths, credentials, prompts or raw provider errors.
 - **Small footprint.** No daemon, no network listener and no stored state. An offline `doctor` checks an installation, and `setup` registers, verifies and removes the server reproducibly.
 
@@ -29,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.7.1**.
+The package version is **0.8.1**.
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
@@ -76,9 +77,17 @@ pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
 pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
 ```
 
-Use `codex:user:pi-session-mcp` for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file.
+Use `codex:user:pi-session-mcp` for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file. The example also registers the two worker skills with `builtin:` references, which resolve to the skills in the package, so the copied example needs no path edits for skills (see [Pi skills](docs/skills.md)).
 
-`pi-session-mcp-doctor` is an offline health check. `pi-session-mcp-setup` plans by default, changes a client registration only with an explicit operation, and never replaces an existing divergent registration. Neither needs credentials, a provider or a model.
+`--apply` registers the server and also installs the controller skill `pi-session-orchestration` for that client, so the agent knows how to drive Pi worker sessions: Claude Code `user` and `local` get `~/.claude/skills/`, Claude Code `project` gets `.claude/skills/` of the project, and Codex gets `~/.agents/skills/`. Setup never replaces a skill it did not install or that you modified. To adjust a skill, copy it into the override directory next to your configuration file and edit the copy:
+
+```bash
+pi-session-mcp-setup --apply --customize-skill pi-session-review
+```
+
+To add a skill of your own, create `skills/<name>/SKILL.md` next to the configuration file and reference it as `builtin:<name>`. Do not edit the installed package or the installed copy in the client.
+
+`pi-session-mcp-doctor` is an offline health check. `pi-session-mcp-setup` plans by default, changes a client registration or skill only with an explicit operation, and never replaces an existing divergent registration or a skill it did not install. Neither needs credentials, a provider or a model.
 
 The [installation guide](docs/installation.md) also covers installing from a release tag with the exact locked dependency tree, the configuration rules, existing registrations, configuration changes, upgrades and removal.
 
@@ -104,6 +113,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 - A workspace alias maps to a directory. Clients can select aliases only.
 - An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
+- An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
 - The server reads the file once at startup. Start a new client session after changing it.
 
 ## Run it by hand
@@ -144,6 +154,7 @@ Operate:
 - [Installation](docs/installation.md)
 - [Client setup reference](docs/client-setup.md): manual registration, the tool flow, deadlines and troubleshooting
 - [External MCP tools in embedded sessions](docs/session-mcp.md)
+- [Pi skills in execution profiles](docs/skills.md)
 - [Changelog](CHANGELOG.md)
 
 Contract and design:
@@ -157,6 +168,7 @@ Contract and design:
 - [ADR 0002: embedded Pi SDK](docs/adr/0002-embedded-pi-sdk.md)
 - [ADR 0003: no new feature phase after the MVP](docs/adr/0003-post-mvp-maintenance.md)
 - [ADR 0004: setup accepts clients by contract, not by version](docs/adr/0004-client-contract-not-version.md)
+- [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
 
 Maintain:
 

package/dist/capabilities.d.ts

@@ -22,5 +22,6 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         model: string;
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
         extensions: string[];
+        skills: string[];
     }[];
 };

package/dist/capabilities.js

@@ -14,7 +14,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             .map((alias) => ({ alias })),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, skills }) => ({
             alias,
             default: isDefault,
             permissionProfile,
@@ -22,6 +22,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             model,
             thinkingLevel,
             extensions: (extensions ?? []).map((extension) => extension.spec),
+            skills: (skills ?? []).map((skill) => skill.alias),
         })),
     };
 }

package/dist/client-adapters/mcp-verifier.js

@@ -1,4 +1,5 @@
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
+import { MAX_PROFILE_SKILLS } from "../skill-catalog.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../package-metadata.js";
 export const MCP_VERIFY_TIMEOUT_MS = 5_000;
 export const MCP_MAX_FRAME_BYTES = 65_536;
@@ -99,7 +100,7 @@ function validCapabilities(value) {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "skills"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
@@ -107,7 +108,10 @@ function validCapabilities(value) {
             && typeof record.model === "string" && record.model.length > 0 && record.model.length <= 256
             && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel)
             && Array.isArray(record.extensions) && record.extensions.length <= MAX_PROFILE_EXTENSIONS
-            && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined);
+            && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined)
+            && Array.isArray(record.skills) && record.skills.length <= MAX_PROFILE_SKILLS
+            && record.skills.every((skill) => typeof skill === "string" && ALIAS_PATTERN.test(skill))
+            && new Set(record.skills).size === record.skills.length;
     }))
         return false;
     const defaults = profiles.filter((profile) => profile.default === true);

package/dist/config.d.ts

@@ -7,6 +7,7 @@ export declare class ConfigError extends Error {
 }
 export declare const configSchema: z.ZodObject<{
     workspaces: z.ZodRecord<z.ZodString, z.ZodString>;
+    skillCatalog: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     executionProfiles: z.ZodRecord<z.ZodString, z.ZodObject<{
         default: z.ZodBoolean;
         permissionProfile: z.ZodEnum<{
@@ -26,6 +27,7 @@ export declare const configSchema: z.ZodObject<{
         }>;
         mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
         extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
@@ -42,6 +44,8 @@ export interface AppConfig {
     readonly executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
     readonly defaultExecutionProfile: string;
     readonly configuration: ConfigurationMetadata;
+    /** Absolute skill override directory next to the configuration file. Internal; never projected. */
+    readonly skillOverrideDirectory: string;
 }
 /**
  * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.

package/dist/config.js

@@ -4,16 +4,20 @@ import { dirname, resolve } from "node:path";
 import { z } from "zod";
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js";
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
+import { builtinSkillName, isSkillCatalogPath, MAX_PROFILE_SKILLS, MAX_SKILL_CATALOG_ENTRIES } from "./skill-catalog.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
+import { builtinSkillPath, skillOverrideDirectory } from "./skill-library.js";
 const alias = z.string().regex(ALIAS_PATTERN);
 const permissionProfile = z.enum(["read-only", "coding"]);
 const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const extensionSpec = z.string().refine((value) => parseExtensionSpec(value) !== undefined);
+const skillCatalogPath = z.string().refine(isSkillCatalogPath);
 const profileSchema = z.object({
     default: z.boolean(), permissionProfile, provider: z.string().trim().min(1).max(256),
     model: z.string().trim().min(1).max(256), thinkingLevel,
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
     extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
+    skills: z.array(alias).max(MAX_PROFILE_SKILLS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
         context.addIssue({ code: "custom", path: ["mcpServers"], message: "MCP tool grants do not match the permission profile" });
@@ -24,6 +28,9 @@ const profileSchema = z.object({
             context.addIssue({ code: "custom", path: ["extensions"], message: "An extension package may appear only once per profile" });
         }
     }
+    if (profile.skills !== undefined && new Set(profile.skills).size !== profile.skills.length) {
+        context.addIssue({ code: "custom", path: ["skills"], message: "A skill alias may appear only once per profile" });
+    }
 });
 const CONFIG_ERROR_MESSAGES = {
     config_path_required: "Configuration path is required",
@@ -40,6 +47,7 @@ export class ConfigError extends Error {
 }
 export const configSchema = z.object({
     workspaces: z.record(alias, z.string().min(1)),
+    skillCatalog: z.record(alias, skillCatalogPath).refine((catalog) => Object.keys(catalog).length <= MAX_SKILL_CATALOG_ENTRIES).optional(),
     executionProfiles: z.record(alias, profileSchema).superRefine((profiles, context) => {
         const entries = Object.entries(profiles);
         if (entries.length === 0)
@@ -50,13 +58,39 @@ export const configSchema = z.object({
         if (defaults.length === 1 && defaults[0][1].permissionProfile !== "read-only")
             context.addIssue({ code: "custom", message: "The default execution profile must be read-only" });
     }),
-}).strict();
+}).strict().superRefine((config, context) => {
+    // A profile may select only cataloged skills; there is no implicit or default skill.
+    const catalog = config.skillCatalog ?? {};
+    for (const [profileAlias, profile] of Object.entries(config.executionProfiles)) {
+        if ((profile.skills ?? []).some((skill) => !Object.hasOwn(catalog, skill))) {
+            context.addIssue({ code: "custom", path: ["executionProfiles", profileAlias, "skills"], message: "A selected skill must be a skillCatalog alias" });
+        }
+    }
+});
 /** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
 export const RELOAD_POLICY = "restart-required";
 export const CONFIGURATION_FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
 function configurationFingerprint(bytes) {
     return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 }
+/**
+ * Resolves a profile's selection against the catalog. Catalog paths resolve like workspaces,
+ * against the configuration file's directory. Two selected aliases on the same path would
+ * load one skill twice under different public names, so they invalidate the configuration.
+ * A `builtin:<name>` value resolves to the library skill: the operator's override, else the shipped one.
+ */
+function resolveSkillSelection(selected, catalog, base, overrideDirectory) {
+    if (selected === undefined || selected.length === 0)
+        return undefined;
+    const resolveEntry = (value) => {
+        const builtin = builtinSkillName(value);
+        return builtin === undefined ? resolve(base, value) : builtinSkillPath(builtin, { overrideDirectory });
+    };
+    const skills = selected.map((skill) => Object.freeze({ alias: skill, path: resolveEntry(catalog[skill]) }));
+    if (new Set(skills.map((skill) => skill.path)).size !== skills.length)
+        throw new ConfigError("invalid_execution_profile_config");
+    return Object.freeze(skills);
+}
 /**
  * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.
  * There is no default file: a server's working directory is the client's project,
@@ -85,14 +119,20 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
         throw error;
     }
     const base = dirname(absoluteConfig);
+    const overrideDirectory = skillOverrideDirectory(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, ...value }]) => [key, Object.freeze({
-            alias: key, ...value,
-            ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
-            ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
-        })]));
+    const catalog = parsed.skillCatalog ?? {};
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, skills, ...value }]) => {
+        const selection = resolveSkillSelection(skills, catalog, base, overrideDirectory);
+        return [key, Object.freeze({
+                alias: key, ...value,
+                ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+                ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
+                ...(selection === undefined ? {} : { skills: selection }),
+            })];
+    }));
     const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
     if (!defaultEntry)
         throw new Error("Execution profile configuration is invalid");
-    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration };
+    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration, skillOverrideDirectory: overrideDirectory };
 }

package/dist/doctor.d.ts

@@ -1,8 +1,9 @@
 import { type AppConfig } from "./config.js";
 import { type ExtensionSpec } from "./extension-spec.js";
+import { type ReleasedSkillTree } from "./skill-library.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "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";
+export type DoctorCheckId = "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";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -30,8 +31,11 @@ export interface DoctorFileSystem {
         readonly isDirectory: () => boolean;
         readonly isFile: () => boolean;
         readonly mtimeMs?: number;
+        readonly size?: number;
     }>;
     readonly access: (path: string, mode: number) => Promise<void>;
+    /** Canonical path; defaults to the real file system when an injected fake omits it. */
+    readonly realpath?: (path: string) => Promise<string>;
 }
 export interface DoctorDependencies {
     readonly packageRoot?: string;
@@ -41,6 +45,8 @@ export interface DoctorDependencies {
     readonly packageMetadata?: () => Promise<DoctorPackageMetadata>;
     /** Reads the installed manifest of a pinned extension; never imports extension code. */
     readonly resolveExtension?: (extension: ExtensionSpec) => Promise<string>;
+    /** Reference trees that resolve legacy skill bases; defaults to the released shipped skills. */
+    readonly releasedSkillTrees?: readonly ReleasedSkillTree[];
 }
 export declare function runDoctor(dependencies?: DoctorDependencies): Promise<DoctorResult>;
 export declare function renderDoctorJson(result: DoctorResult): string;

package/dist/doctor.js

@@ -1,11 +1,14 @@
-import { access, readFile, readdir, stat } from "node:fs/promises";
+import { access, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
 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 { 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"];
+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 }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -62,6 +65,44 @@ async function productionBuildInputMtimes(root) {
     }
     return mtimes;
 }
+/**
+ * Compares the shipped skills with the fingerprints recorded when the operator copied them.
+ * 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, released) {
+    if (overrideDirectory === undefined)
+        return [];
+    let bases;
+    try {
+        bases = await readSkillBases(overrideDirectory);
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            return [warning("skill_override_outdated", "skill:bases", "repair or remove the skill bases file")];
+        throw error;
+    }
+    const checks = [];
+    for (const [name, base] of Object.entries(bases).sort(([a], [b]) => a.localeCompare(b))) {
+        let fingerprint;
+        try {
+            fingerprint = (await readSkillTree(join(shippedDirectory, name))).fingerprint;
+        }
+        catch {
+            continue;
+        }
+        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;
+}
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
@@ -195,6 +236,38 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config) {
+        for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
+            const canonical = new Set();
+            for (const skill of profile.skills ?? []) {
+                const subject = `${alias}:${skill.alias}`;
+                let real;
+                try {
+                    const info = await fs.stat(skill.path);
+                    if (!info.isFile() || (info.size ?? 0) > MAX_SKILL_FILE_BYTES)
+                        throw new Error("unusable skill file");
+                    await fs.access(skill.path, constants.R_OK);
+                    real = await (fs.realpath ?? realpath)(skill.path);
+                }
+                catch (error) {
+                    if (isMissing(error))
+                        checks.push(failure("skill_missing", subject, "create the skill file or fix its skillCatalog entry"));
+                    else
+                        checks.push(ok("skill_missing", subject), failure("skill_unreadable", subject, "point the skillCatalog entry to a readable SKILL.md within the size limit"));
+                    continue;
+                }
+                checks.push(ok("skill_missing", subject), ok("skill_unreadable", subject));
+                if (canonical.has(real))
+                    checks.push(failure("skill_duplicate", subject, "select each skill file only once per profile"));
+                else {
+                    canonical.add(real);
+                    checks.push(ok("skill_duplicate", subject));
+                }
+            }
+        }
+    }
+    if (config)
+        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/dist/execution-profile.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionSpec } from "./extension-spec.js";
 import { type McpServers } from "./mcp-config.js";
+import type { SkillSelection } from "./skill-catalog.js";
 export declare const ALIAS_PATTERN: RegExp;
 export type PermissionProfile = "read-only" | "coding";
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -13,6 +14,8 @@ export interface ConfiguredExecutionProfile {
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
+    /** The selected catalog skills in configured order; absent when the profile selects none. */
+    readonly skills?: readonly SkillSelection[];
 }
 /** The immutable, server-side selection passed to the Pi adapter. */
 export interface ResolvedExecutionProfile {
@@ -23,6 +26,7 @@ export interface ResolvedExecutionProfile {
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
+    readonly skills?: readonly SkillSelection[];
 }
 export declare function toResolvedExecutionProfile(profile: ConfiguredExecutionProfile): ResolvedExecutionProfile;
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/dist/execution-profile.js

@@ -9,6 +9,7 @@ export function toResolvedExecutionProfile(profile) {
         thinkingLevel: profile.thinkingLevel,
         ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
         ...(profile.extensions === undefined ? {} : { extensions: profile.extensions }),
+        ...(profile.skills === undefined ? {} : { skills: profile.skills }),
     });
 }
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/dist/override-lock.d.ts

@@ -0,0 +1,34 @@
+import { type StatfsReader } 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 declare const SKILL_BASES_LOCK_FILE = ".pi-session-mcp-bases.lock";
+export declare const DEFAULT_OVERRIDE_LOCK_TIMEOUT_MS = 30000;
+export declare class OverrideLockError extends Error {
+    readonly code: "override_lock_busy" | "override_lock_unavailable";
+    constructor(code: "override_lock_busy" | "override_lock_unavailable");
+}
+export interface OverrideLockOptions {
+    /** Acquisition bound; a busy lock after this fails with `override_lock_busy`. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Test seams for the platform gate; the defaults describe this process. */
+    readonly platform?: NodeJS.Platform;
+    readonly flockCandidates?: readonly string[];
+    readonly isTrustedBinary?: (path: string) => boolean;
+    readonly readStatfs?: StatfsReader;
+}
+export interface OverrideLock {
+    /** Closes the descriptor that holds the lock; safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * 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 declare function acquireOverrideLock(overrideDirectory: string, options?: OverrideLockOptions): Promise<OverrideLock>;

package/dist/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/dist/pi-adapter.d.ts

@@ -13,7 +13,7 @@ export interface PiAppliedSelection {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
 }
-export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "pi_session_creation_failed";
+export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "skill_load_failed" | "pi_session_creation_failed";
 export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);
@@ -23,10 +23,12 @@ export interface PiSessionHandle {
     /** Only whitelisted, post-verified selection metadata may cross the adapter boundary. */
     readonly appliedSelection: PiAppliedSelection;
     /**
-     * `onActivity` is an optional content-free liveness callback, invoked after a completed
-     * tool execution and after a completed assistant message. It receives no event payload
-     * and must only be used for timestamping; it never carries tool names, arguments,
-     * results, text, paths, or credentials.
+     * `onActivity` is an optional content-free liveness callback, invoked on observed public
+     * SDK activity of the running prompt: assistant message start, update and end, and tool
+     * execution start, update and end. Streaming is activity, not evidence of finished or
+     * useful work, and internal work without a public event stays invisible. It receives no
+     * event payload and must only be used for timestamping; it never carries tool names,
+     * arguments, results, text, paths, or credentials.
      */
     prompt(text: string, preflight: (accepted: boolean) => void, onActivity?: () => void): Promise<PiTurnOutcome>;
     abort(): Promise<void>;

package/dist/pi-adapter.js

@@ -14,6 +14,7 @@ const PI_SESSION_CREATION_MESSAGES = {
     extension_version_mismatch: "Configured Pi extension version is not installed",
     extension_load_failed: "Configured Pi extension could not be loaded",
     extension_tool_conflict: "Configured Pi extension tools conflict",
+    skill_load_failed: "Configured Pi skill could not be loaded",
     pi_session_creation_failed: "Pi session creation failed",
 };
 export class PiSessionCreationError extends Error {

package/dist/pi-skills.d.ts

@@ -0,0 +1,17 @@
+import { type Stats } from "node:fs";
+import { loadSkills, type Skill } from "@earendil-works/pi-coding-agent";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { type SkillSelection } from "./skill-catalog.js";
+export declare class PiSkillError extends PiSessionCreationError {
+    readonly alias?: string | undefined;
+    constructor(alias?: string | undefined);
+}
+interface SkillDependencies {
+    readonly stat: (path: string) => Promise<Stats>;
+    readonly access: (path: string, mode: number) => Promise<void>;
+    readonly realpath: (path: string) => Promise<string>;
+    readonly loadSkills: typeof loadSkills;
+}
+/** Load only the configured files, independently of package discovery and SDK deduplication. */
+export declare function loadSelectedSkills(selection: readonly SkillSelection[], cwd: string, dependencies?: Partial<SkillDependencies>): Promise<Skill[]>;
+export {};