pi-session-mcp 0.7.1 → 0.8.1

package/dist/pi-skills.js

@@ -0,0 +1,64 @@
+import { constants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadSkills } from "@earendil-works/pi-coding-agent";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
+export class PiSkillError extends PiSessionCreationError {
+    alias;
+    constructor(alias) {
+        super("skill_load_failed");
+        this.alias = alias;
+        this.name = "PiSkillError";
+    }
+}
+/** Load only the configured files, independently of package discovery and SDK deduplication. */
+export async function loadSelectedSkills(selection, cwd, dependencies = {}) {
+    if (selection.length === 0)
+        return [];
+    const fs = { stat, access, realpath, loadSkills, ...dependencies };
+    const paths = [];
+    const canonical = new Set();
+    try {
+        for (const selected of selection) {
+            try {
+                const path = resolve(selected.path);
+                const info = await fs.stat(path);
+                if (!info.isFile() || info.size > MAX_SKILL_FILE_BYTES)
+                    throw new PiSkillError(selected.alias);
+                await fs.access(path, constants.R_OK);
+                const real = await fs.realpath(path);
+                if (canonical.has(real))
+                    throw new PiSkillError(selected.alias);
+                canonical.add(real);
+                paths.push(path);
+            }
+            catch {
+                throw new PiSkillError(selected.alias);
+            }
+        }
+        const result = fs.loadSkills({ cwd, agentDir: cwd, skillPaths: paths, includeDefaults: false });
+        if (result.diagnostics.length > 0) {
+            const aliases = new Set(result.diagnostics.map((diagnostic) => {
+                const index = paths.indexOf(diagnostic.path ?? "");
+                return index < 0 ? undefined : selection[index].alias;
+            }));
+            throw new PiSkillError(aliases.size === 1 ? [...aliases][0] : undefined);
+        }
+        if (result.skills.length !== paths.length) {
+            const missing = selection.filter((_selected, index) => !result.skills.some((skill) => skill.filePath === paths[index]));
+            throw new PiSkillError(missing.length === 1 ? missing[0].alias : undefined);
+        }
+        return paths.map((path, index) => {
+            const matches = result.skills.filter((skill) => skill.filePath === path);
+            if (matches.length !== 1 || matches[0].disableModelInvocation === true)
+                throw new PiSkillError(selection[index].alias);
+            return matches[0];
+        });
+    }
+    catch (error) {
+        if (error instanceof PiSkillError)
+            throw error;
+        throw new PiSkillError();
+    }
+}

package/dist/sdk-pi-adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, type Skill, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { type ExtensionSpec } from "./extension-spec.js";
 import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
@@ -11,7 +11,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -22,6 +22,8 @@ export interface SdkPiAdapterDiagnostic {
     readonly discoveredToolCount?: number;
     /** `<name>@<version>` of the extension that failed to resolve; never a path. */
     readonly extension?: string;
+    /** The failing configured catalog alias, never a skill-file name or path. */
+    readonly skill?: string;
 }
 /** The Pi SDK session-lifecycle API used for profiles with extensions; injectable for tests. */
 export interface ExtensionSdk {
@@ -64,7 +66,7 @@ export type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightR
  * typecheck (and therefore the Pi SDK canary) instead of being mapped silently.
  */
 export declare function admitsTurn(disposition: PromptDisposition): boolean;
-export declare function createPhase0ResourceLoader(cwd: string): Promise<{
+export declare function createPhase0ResourceLoader(cwd: string, skills?: readonly Skill[]): Promise<{
     resourceLoader: DefaultResourceLoader;
     settingsManager: SettingsManager;
 }>;
@@ -83,6 +85,8 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
     private createWithExtensions;
+    private loadSkills;
+    private checkResources;
     /** Provider, model, authentication and availability, exactly as configured. */
     private resolveVerifiedModel;
     private connectMcpTools;

package/dist/sdk-pi-adapter.js

@@ -4,6 +4,7 @@ import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-
 import { createStdioMcpConnection } from "./mcp-stdio-client.js";
 import { PiSessionCreationError, } from "./pi-adapter.js";
 import { resolvePiExtension } from "./pi-extensions.js";
+import { loadSelectedSkills, PiSkillError } from "./pi-skills.js";
 import { composeSessionTools, PROFILE_TOOLS } from "./session-tools.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 export const AUTH_OPERATION_TIMEOUT_MS = 5_000;
@@ -191,12 +192,31 @@ class SdkHandle {
             }
             catch { /* Liveness reporting is best effort and content-free. */ }
         };
+        // Activity is the public SDK stream of this prompt: assistant message start, update and end, and
+        // tool execution start, update and end. Only the event discriminant and the message role are
+        // inspected: delta text, thinking, tool arguments and partial results are never read, stored or
+        // forwarded. Streaming is activity, not evidence of finished work; only the last assistant
+        // `message_end` is the answer, and the terminal state comes from the completion paths below.
         const unsubscribe = this.session.subscribe((event) => {
-            if (event.type === "tool_execution_end")
-                reportActivity();
-            else if (event.type === "message_end" && isAssistantMessage(event.message)) {
-                finalAssistant = event.message;
-                reportActivity();
+            switch (event.type) {
+                case "tool_execution_start":
+                case "tool_execution_update":
+                case "tool_execution_end":
+                    reportActivity();
+                    break;
+                case "message_start":
+                case "message_update":
+                    if (hasAssistantRole(event.message))
+                        reportActivity();
+                    break;
+                case "message_end":
+                    if (isAssistantMessage(event.message)) {
+                        finalAssistant = event.message;
+                        reportActivity();
+                    }
+                    break;
+                default:
+                    break;
             }
         });
         let preflightSeen = false;
@@ -263,14 +283,20 @@ function isAssistantMessage(message) {
     const candidate = message;
     return candidate.role === "assistant" && Array.isArray(candidate.content);
 }
+/** Role check only: streaming messages are never inspected for content. */
+function hasAssistantRole(message) {
+    return typeof message === "object" && message !== null && message.role === "assistant";
+}
 function isTextBlock(block) {
     if (!block || typeof block !== "object")
         return false;
     const candidate = block;
     return candidate.type === "text" && typeof candidate.text === "string";
 }
-/** Resource-loader options for every embedded session: no discovery, skills, templates or themes. */
-function phase0ResourceLoaderOptions() {
+/** Independently validated skills replace package and extension discovery on every reload. */
+function phase0ResourceLoaderOptions(skills) {
+    // Keep the closure's snapshot private: the SDK may annotate or mutate returned objects.
+    const selected = skills.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } }));
     return {
         noExtensions: true,
         noSkills: true,
@@ -281,11 +307,14 @@ function phase0ResourceLoaderOptions() {
         appendSystemPrompt: [],
         systemPromptOverride: () => undefined,
         appendSystemPromptOverride: () => [],
+        skillsOverride: () => ({ skills: selected.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } })), diagnostics: [] }),
+        promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+        themesOverride: () => ({ themes: [], diagnostics: [] }),
     };
 }
-export async function createPhase0ResourceLoader(cwd) {
+export async function createPhase0ResourceLoader(cwd, skills = []) {
     const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
-    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions() });
+    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills) });
     await resourceLoader.reload();
     return { resourceLoader, settingsManager };
 }
@@ -310,6 +339,7 @@ export class SdkPiSessionAdapter {
         if (extensions.length > 0)
             return this.createWithExtensions(input, extensions);
         const { executionProfile } = input;
+        const skills = await this.loadSkills(input);
         let runtime;
         try {
             runtime = await this.getRuntime();
@@ -321,7 +351,7 @@ export class SdkPiSessionAdapter {
         let resourceLoader;
         let settingsManager;
         try {
-            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd));
+            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills));
         }
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
@@ -347,10 +377,11 @@ export class SdkPiSessionAdapter {
             await mcpTools.close();
             throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
         }
-        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined);
+        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills);
     }
     async createWithExtensions(input, extensions) {
         const { cwd, executionProfile } = input;
+        const skills = await this.loadSkills(input);
         const directories = [];
         for (const extension of extensions) {
             try {
@@ -377,15 +408,18 @@ export class SdkPiSessionAdapter {
                 agentDir: cwd,
                 modelRuntime: runtime,
                 settingsManager: SettingsManager.inMemory(undefined, { projectTrusted: false }),
-                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(), additionalExtensionPaths: directories },
+                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills), additionalExtensionPaths: directories },
             }));
+            this.checkResources(services.resourceLoader, skills, executionProfile, "extension_load");
             const loaded = services.resourceLoader.getExtensions();
             if (loaded.errors.length > 0 || services.diagnostics.some((diagnostic) => diagnostic.type === "error")) {
                 throw new Error("extension load reported errors");
             }
             extensionTools = registeredExtensionTools(services);
         }
-        catch {
+        catch (error) {
+            if (error instanceof PiSessionCreationError)
+                throw error;
             throw this.failure(executionProfile, "extension_load", "extension_load_failed");
         }
         const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
@@ -434,6 +468,7 @@ export class SdkPiSessionAdapter {
             bound = true;
             if (bindErrors > 0)
                 throw new Error("extension hook reported errors while binding");
+            this.checkResources(sessionRuntime.session.resourceLoader, skills, executionProfile, "extension_bind");
             // A `session_start` handler may register a tool that replaces a built-in or granted tool.
             // Tools an extension registers later, during a turn, are not re-checked: allowlisted
             // extensions are trusted code.
@@ -441,15 +476,44 @@ export class SdkPiSessionAdapter {
             if (!recheck || recheck.length !== tools.length || recheck.some((name, index) => name !== tools[index]))
                 conflict = true;
         }
-        catch {
+        catch (error) {
             await cleanUp();
+            if (error instanceof PiSessionCreationError)
+                throw error;
             throw this.failure(executionProfile, "extension_bind", "extension_load_failed");
         }
         if (conflict) {
             await cleanUp();
             throw this.failure(executionProfile, "extension_bind", "extension_tool_conflict");
         }
-        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset");
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills);
+    }
+    async loadSkills(input) {
+        try {
+            return await loadSelectedSkills(input.executionProfile.skills ?? [], input.cwd);
+        }
+        catch (error) {
+            throw this.failure(input.executionProfile, "skill_load", "skill_load_failed", error instanceof PiSkillError && error.alias !== undefined ? { skill: error.alias } : undefined);
+        }
+    }
+    checkResources(loader, skills, executionProfile, stage) {
+        let actual;
+        try {
+            actual = loader.getSkills().skills;
+        }
+        catch {
+            throw this.failure(executionProfile, stage, "skill_load_failed");
+        }
+        // Compare a multiset so duplicate entries cannot satisfy a selected file twice.
+        const identity = (skill) => JSON.stringify([skill.filePath, skill.name]);
+        const expected = skills.map(identity).sort();
+        const received = actual.map(identity).sort();
+        if (expected.length !== received.length || expected.some((entry, index) => entry !== received[index])) {
+            throw this.failure(executionProfile, stage, "skill_load_failed");
+        }
+        if (loader.getPrompts().prompts.length > 0 || loader.getThemes().themes.length > 0) {
+            throw this.failure(executionProfile, stage, "pi_session_creation_failed");
+        }
     }
     /** Provider, model, authentication and availability, exactly as configured. */
     async resolveVerifiedModel(runtime, executionProfile) {
@@ -513,8 +577,9 @@ export class SdkPiSessionAdapter {
     /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
     async admit(session, executionProfile, tools, mcpTools, disposeSession, toolMismatch, 
     // `subset` lets an extension narrow its own active tools; nothing outside the allowlist may be active.
-    toolCheck = "exact") {
+    toolCheck = "exact", skills = []) {
         try {
+            this.checkResources(session.resourceLoader, skills, executionProfile, "postcheck");
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
                 throw this.failure(executionProfile, "postcheck", "execution_selection_mismatch");
             }
@@ -570,6 +635,7 @@ export class SdkPiSessionAdapter {
                 ...(metadata?.toolAlias === undefined ? {} : { toolAlias: metadata.toolAlias }),
                 ...(metadata?.discoveredToolCount === undefined ? {} : { discoveredToolCount: metadata.discoveredToolCount }),
                 ...(metadata?.extension === undefined ? {} : { extension: metadata.extension }),
+                ...(metadata?.skill === undefined ? {} : { skill: metadata.skill }),
             });
         }
         catch {

package/dist/server.js

@@ -42,6 +42,7 @@ const capabilitiesSchema = z.object({
         model: z.string(),
         thinkingLevel: thinkingLevelSchema,
         extensions: z.array(z.string()),
+        skills: z.array(aliasSchema),
     }).strict()),
 }).strict();
 function result(value, isError = false) {

package/dist/session-registry.d.ts

@@ -16,10 +16,11 @@ export interface SessionView {
     lastError?: string;
 }
 /**
- * `updatedAt` is the registry's own last-activity stamp: while a turn runs it advances on a
- * completed tool execution or completed assistant message, then freezes at the terminal
- * transition. It is a liveness lower bound, not a progress count, and does not prove that a
- * silent turn is healthy.
+ * `updatedAt` is the time of the last observed public SDK activity of the turn (assistant
+ * message start, update and end; tool execution start, update and end), then freezes at the
+ * terminal transition. Streaming is activity, not evidence of finished or useful work, and
+ * internal work without a public event stays invisible. It is a liveness lower bound, not a
+ * progress count, and does not prove that a silent turn is healthy.
  */
 export interface TurnView {
     turnId: string;
@@ -81,8 +82,9 @@ export declare class SessionRegistry {
     private completeTurn;
     private failTurn;
     /**
-     * Liveness only. A completed tool execution or assistant message advances this turn,
-     * never another turn or the session. Activity after accepted preflight but before
+     * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
+     * execution start, update and end) advances this turn, never another turn or the session.
+     * Streaming is activity, not evidence of finished or useful work. Activity after accepted preflight but before
      * publication is stamped and applied only if the turn is published; callbacks before
      * acceptance or after terminal cleanup cannot publish or revive a turn.
      */

package/dist/session-registry.js

@@ -273,8 +273,9 @@ export class SessionRegistry {
         entry.turn = undefined; if (entry.turnPromise)
         entry.turnPromise = undefined; entry.state = "failed"; entry.updatedAt = turn.updatedAt; entry.lastError = "Pi turn failed"; }
     /**
-     * Liveness only. A completed tool execution or assistant message advances this turn,
-     * never another turn or the session. Activity after accepted preflight but before
+     * Liveness only. Observed public SDK activity (assistant message start, update and end; tool
+     * execution start, update and end) advances this turn, never another turn or the session.
+     * Streaming is activity, not evidence of finished or useful work. Activity after accepted preflight but before
      * publication is stamped and applied only if the turn is published; callbacks before
      * acceptance or after terminal cleanup cannot publish or revive a turn.
      */

package/dist/setup-cli.d.ts

@@ -3,6 +3,8 @@ import type { SetupResult } from "./setup-result.js";
 /** Small argv adapter; command execution remains injected in SetupClientAdapter. */
 export interface SetupCliRequest extends SetupRequest {
     readonly json: boolean;
+    /** `--customize-skill <name>`: copies a shipped skill into the override directory instead of touching clients. */
+    readonly customizeSkill?: string;
 }
 export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
 export declare function runSetupCli(argv: readonly string[], orchestrator: SetupOrchestrator): Promise<SetupResult>;

package/dist/setup-cli.js

@@ -2,6 +2,7 @@ export function parseSetupArgs(argv) {
     let operation;
     let json = false;
     const targets = [];
+    let customizeSkill;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--json") {
@@ -24,8 +25,23 @@ export function parseSetupArgs(argv) {
             targets.push({ client: parts[0], scope: parts[1], alias: parts[2] });
             continue;
         }
+        if (argument === "--customize-skill") {
+            if (customizeSkill !== undefined)
+                throw new Error("customize_skill_repeated");
+            const value = argv[++index];
+            if (value === undefined || value === "" || value.startsWith("-"))
+                throw new Error("customize_skill_invalid");
+            customizeSkill = value;
+            continue;
+        }
         throw new Error("argument_unsupported");
     }
+    if (customizeSkill !== undefined) {
+        // Skill customization is a dry-run or an explicit apply; it never targets a client.
+        if (targets.length > 0 || (operation !== undefined && operation !== "dry-run" && operation !== "apply"))
+            throw new Error("customize_skill_combination");
+        return operation ? { operation, targets, json, customizeSkill } : { targets, json, customizeSkill };
+    }
     return operation ? { operation, targets, json } : { targets, json };
 }
 export async function runSetupCli(argv, orchestrator) {

package/dist/setup-main.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createProductionSetup } from "./setup.js";
-/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias`. */
+/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias` or `[--apply] --customize-skill <name>`. */
 export interface SetupMainDependencies {
     readonly createSetup?: typeof createProductionSetup;
     readonly packageRoot?: string;

package/dist/setup-main.js

@@ -5,6 +5,8 @@ import { isEntryPoint } from "./entry-point.js";
 import { createProcessRunner } from "./setup-process.js";
 import { currentSetupPlatform } from "./setup-platform.js";
 import { createProductionSetup, isSupportedTarget } from "./setup.js";
+import { customizeSkill } from "./skill-customize.js";
+import { SKILL_NAME_PATTERN } from "./skill-library.js";
 import { formatSetupHuman, formatSetupResult, parseSetupArgs } from "./setup-cli.js";
 import { result } from "./setup-result.js";
 export async function main(argv = process.argv.slice(2), dependencies = {}) {
@@ -18,11 +20,21 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
         return write(cliFailure("dry-run", [], "usage_invalid", 64), json);
     }
     const operation = request.operation ?? "dry-run";
+    const failureTargets = request.customizeSkill === undefined ? request.targets : [skillTarget(request.customizeSkill)];
     if (!currentSetupPlatform())
-        return write(cliFailure(operation, request.targets, "platform_unsupported", 1), request.json);
+        return write(cliFailure(operation, failureTargets, "platform_unsupported", 1), request.json);
     const config = process.env.PI_SESSION_MCP_CONFIG;
     if (!config)
-        return write(cliFailure(operation, request.targets, "config_required", 1), request.json);
+        return write(cliFailure(operation, failureTargets, "config_required", 1), request.json);
+    if (request.customizeSkill !== undefined) {
+        const name = request.customizeSkill;
+        try {
+            return write(await customizeSkill({ name, configPath: resolve(config), apply: operation === "apply", ...(dependencies.packageRoot === undefined ? {} : { packageRoot: dependencies.packageRoot }) }), request.json);
+        }
+        catch {
+            return write(cliFailure(operation, [skillTarget(name)], "skill_customize_failed", 1), request.json);
+        }
+    }
     const root = dependencies.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
     const controller = new AbortController();
     let interrupted;
@@ -51,8 +63,11 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
         process.removeListener("SIGTERM", onTerminate);
     }
 }
+/** The skill name is echoed only when it is a valid name; arbitrary input never reaches a report. */
+function skillTarget(name) { return { client: "skills", scope: "override", alias: SKILL_NAME_PATTERN.test(name) ? name : "invalid" }; }
+function isReportableTarget(target) { return isSupportedTarget(target) || (target.client === "skills" && target.scope === "override" && (target.alias === "invalid" || SKILL_NAME_PATTERN.test(target.alias))); }
 function cliFailure(operation, targets, code, exitCode) {
-    const safeTargets = targets.filter(isSupportedTarget);
+    const safeTargets = targets.filter(isReportableTarget);
     const reported = safeTargets.length === targets.length && safeTargets.length > 0 ? safeTargets : [{ client: "invalid", scope: "invalid", alias: "invalid" }];
     return result(operation, reported.map((target) => ({ target, status: "failed", code })), "failed", exitCode);
 }

package/dist/setup-ownership.d.ts

@@ -6,6 +6,14 @@ export interface OwnershipRecord {
     readonly previous: "absent" | "equivalent";
     readonly phase: "pending" | "owned";
     readonly transactionId: string;
+    /**
+     * Skill records only, while pending: the fingerprint of setup's own copy that the pending
+     * update replaces, so an interrupted update can still be completed or removed. The
+     * transaction id also names the update's intermediate directories, so recovery needs no path.
+     * Skill fingerprints are `v2:` values; a bare 64-hex value is a record that 0.8.0 wrote and
+     * names a tree only once a trusted reference proves it.
+     */
+    readonly replaces?: string;
 }
 export interface RegistrationSnapshot {
     /** Opaque adapter-owned snapshot; implementations must not persist secrets. */
@@ -51,3 +59,4 @@ export declare class DurableOwnershipStore implements OwnershipStore {
     private withLock;
     private write;
 }
+export declare function isRecord(value: unknown): value is OwnershipRecord;

package/dist/setup-ownership.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { acquireSetupGuardian } from "./setup-process.js";
 import { assertSupportedFilesystem, currentSetupPlatform, openLockedDarwin } from "./setup-platform.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, SKILL_NAME_PATTERN, SKILL_TREE_FINGERPRINT_PATTERN } from "./skill-library.js";
 /** Safe default for one process; callers needing recovery inject a durable store. */
 export class MemoryOwnershipStore {
     entries = new Map();
@@ -209,10 +210,36 @@ async function syncDirectory(path) {
         await handle.close();
     }
 }
-function isRecord(value) { if (!value || typeof value !== "object")
-    return false; const x = value; if (!exactKeys(x, ["target", "fingerprint", "previous", "phase", "transactionId"]))
-    return false; const t = x.target; if (!t || typeof t !== "object")
-    return false; const target = t; if (!exactKeys(target, ["client", "scope", "alias"]))
-    return false; const client = target.client; const scope = target.scope; return (client === "codex" || client === "claude-code") && typeof scope === "string" && (client === "codex" ? scope === "user" : ["user", "project", "local"].includes(scope)) && target.alias === "pi-session-mcp" && typeof x.fingerprint === "string" && /^[a-f0-9]{64}$/.test(x.fingerprint) && (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" && typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId); }
+/** `skill:<name>` for a home slot; `skill:<name>@<16 hex>` for a project slot bound to an opaque project identity. */
+const SKILL_RECORD_ALIAS = /^skill:([^@]+)(?:@([0-9a-f]{16}))?$/;
+export function isRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const x = value;
+    const keys = ["target", "fingerprint", "previous", "phase", "transactionId"];
+    if (!exactKeys(x, keys) && !exactKeys(x, [...keys, "replaces"]))
+        return false;
+    if (!x.target || typeof x.target !== "object")
+        return false;
+    const target = x.target;
+    if (!exactKeys(target, ["client", "scope", "alias"]))
+        return false;
+    const { client, scope, alias } = target;
+    const registration = alias === "pi-session-mcp" &&
+        (client === "codex" ? scope === "user" : client === "claude-code" && typeof scope === "string" && ["user", "project", "local"].includes(scope));
+    const skillAlias = typeof alias === "string" ? SKILL_RECORD_ALIAS.exec(alias) : null;
+    const skill = skillAlias !== null && SKILL_NAME_PATTERN.test(skillAlias[1]) &&
+        (client === "codex" ? scope === "user" && skillAlias[2] === undefined
+            : client === "claude-code" && ((scope === "user" && skillAlias[2] === undefined) || (scope === "project" && skillAlias[2] !== undefined)));
+    // A registration fingerprint is a snapshot hash; a skill fingerprint is a version 2 tree value or a 0.8.0 legacy one.
+    const validFingerprint = (value) => typeof value === "string" &&
+        (skill ? SKILL_TREE_FINGERPRINT_PATTERN.test(value) || LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) : /^[a-f0-9]{64}$/.test(value));
+    // `replaces` belongs only to a pending skill record.
+    if ("replaces" in x && !(skill && x.phase === "pending" && validFingerprint(x.replaces)))
+        return false;
+    return (registration || skill) && validFingerprint(x.fingerprint) &&
+        (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" &&
+        typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId);
+}
 function exactKeys(value, expected) { const keys = Object.keys(value).sort(); return keys.length === expected.length && [...expected].sort().every((key, index) => keys[index] === key); }
 const key = (target) => `${target.client}\u0000${target.scope}\u0000${target.alias}`;

package/dist/setup-skills.d.ts

@@ -0,0 +1,76 @@
+import { type ReleasedSkillTree } from "./skill-library.js";
+import type { OwnershipAccess } from "./setup-ownership.js";
+import type { SetupFinding, SetupOperation, SetupTarget } from "./setup-result.js";
+export interface SetupSkillInstaller {
+    /** Called under the registration's ownership transaction for every mutation. */
+    run(operation: SetupOperation, target: SetupTarget, ownership: OwnershipAccess): Promise<readonly SetupFinding[]>;
+    /**
+     * Whether setup still owns an installed skill of exactly this registration target, so that a
+     * remove may finish the skill cleanup after the registration is already gone.
+     */
+    owns(target: SetupTarget, ownership: OwnershipAccess): Promise<boolean>;
+}
+export interface SetupSkillRoots {
+    readonly packageRoot: string;
+    readonly configPath: string;
+    readonly home: string;
+    readonly cwd: string;
+}
+/** The crash-relevant points of an update, in order. Only a test seam observes them. */
+export type SkillCheckpoint = "staged" | "backup-renamed" | "installed" | "trash-renamed" | "trash-entry-removed" | "trash-deleted" | "before-ownership";
+export interface SetupSkillDependencies {
+    /** Trusted released trees that prove 0.8.0 records; defaults to the shipped table. */
+    readonly released?: readonly ReleasedSkillTree[];
+    /** Test seam, called after each step in `SkillCheckpoint` completed; defaults to a no-op. */
+    readonly checkpoint?: (step: SkillCheckpoint) => void | Promise<void>;
+}
+/** Paths remain internal. Ownership identifies a client slot, never its location. */
+export declare class FileSetupSkillInstaller implements SetupSkillInstaller {
+    private readonly roots;
+    private readonly dependencies;
+    constructor(roots: SetupSkillRoots, dependencies?: SetupSkillDependencies);
+    run(operation: SetupOperation, target: SetupTarget, ownership: OwnershipAccess): Promise<readonly SetupFinding[]>;
+    owns(target: SetupTarget, ownership: OwnershipAccess): Promise<boolean>;
+    private step;
+    /**
+     * The slot path and its ownership key. A project may be untrusted: only its root is
+     * canonicalized, and a link below it (for example `.claude` pointing elsewhere) makes the
+     * slot divergent, so setup never writes outside the project. In the operator's home the
+     * client's skills directory may be the operator's own link, for example into a dotfiles
+     * checkout, so it is followed. The skill entry itself is never followed in either place.
+     * A project slot's ownership is bound to an opaque, path-free identity of the project, so a
+     * remove in another project never touches this project's copy.
+     */
+    private location;
+    private library;
+    /**
+     * Whether the record names this installed tree: its version 2 value, or a 0.8.0 value that a
+     * trusted reference proves for exactly these bytes. A bare legacy value never proves identity.
+     */
+    private ownsTree;
+    private skill;
+    /**
+     * Installs the new tree through the transaction's own intermediates. A failure leaves them for
+     * recovery; nothing here deletes by guess.
+     */
+    private replace;
+    /**
+     * Deletes the backup only after it is verified to be the exact old copy: it is renamed to the
+     * transaction's trash name first, so the deletion never leaves an unverifiable partial tree
+     * under the backup name.
+     */
+    private discardBackup;
+    /** Deletes the transaction's trash entry by entry, so a crash leaves only a smaller partial tree. */
+    private discardTrash;
+    /**
+     * Settles an interrupted update of the pending record's transaction, inside the ownership
+     * transaction. Only directories with this transaction's exact names are examined, and only
+     * verified ones are deleted: the backup must equal the replaced copy, the staging directory
+     * the target or an interrupted write of it. Anything else stays and is reported.
+     *
+     * apply, slot absent: a complete staging directory is renamed into the slot (forward);
+     * otherwise a verified backup is moved back. remove and rollback do not restore, they delete
+     * what is verified and leave the slot to the caller.
+     */
+    private recover;
+}