@hasna/skills 0.8.9 → 0.8.11

package/dist/lib/agent-adapters.d.ts

@@ -1,5 +1,6 @@
 export declare const INTEGRATION_AGENTS: readonly ["claude", "codex", "gemini", "opencode", "cursor", "hermes"];
 export type IntegrationAgent = typeof INTEGRATION_AGENTS[number];
+export declare function renderAgentHookCommand(command: string, agent: IntegrationAgent, profileId: string, event: string): string;
 export declare const AGENT_ADAPTERS: {
     readonly claude: {
         readonly root: ".claude/skills";

package/dist/lib/agent-codex-trust.d.ts

@@ -0,0 +1,42 @@
+import { connectCodexHookRpc } from "./codex-hook-rpc.js";
+import { type ReviewedSkillsCli } from "./codex-hook-trust-identity.js";
+export interface CodexNativeHookTrustOptions {
+    home?: string;
+    dataDir?: string;
+    codexCommand?: string;
+    apply?: boolean;
+    reviewedPlanDigest?: string;
+    reviewedSkillsCli?: ReviewedSkillsCli;
+}
+type Connect = typeof connectCodexHookRpc;
+/** Deliberately separate from filesystem hook installation: native trust is an
+ * explicit authorization of exact owned commands, never a broad trust bypass. */
+export declare function enrollCodexNativeHooks(options?: CodexNativeHookTrustOptions, connect?: Connect): Promise<{
+    planDigest: string;
+    skillsCli: {
+        path: string;
+        version: string;
+        sha256: string;
+        manifestSha256: string;
+    };
+    nativeVersion: string;
+    ownedNativeProcessId: number | undefined;
+    agent: string;
+    applied: boolean;
+    planned: {
+        key: any;
+        event: string;
+        command: string;
+        handlerType: any;
+        timeoutSec: any;
+        sourcePath: any;
+        currentHash: any;
+        enabled: any;
+        trustStatus: any;
+    }[];
+    nativeEligible: boolean;
+    transport: string;
+    existingSessionsReloaded: boolean;
+    nativeExecutionVerified: boolean;
+}>;
+export {};

package/dist/lib/agent-discovery.d.ts

@@ -1,10 +1,12 @@
 import type { IntegrationAgent } from "./agent-adapters.js";
 import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
+import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 export { captureDiscoveryDirectories, type DiscoveryDirectory } from "./agent-discovery-directories.js";
 export interface DiscoverySource {
     path: string;
     sha256: string | null;
-    hashMode?: "bytes" | "path-bytes";
+    hashMode?: "bytes" | "path-bytes" | "claude-plugin-registry" | "claude-marketplace-registry";
+    managedPlugins?: ManagedPluginRegistrationWitness[];
     format?: "json" | "toml" | "yaml";
     fields?: string[];
 }
@@ -35,7 +37,7 @@ export declare function captureDiscoveryPathSources(paths: string[]): DiscoveryS
 /** Project settings can introduce a higher-precedence discovery source. Until
  * its native merge format is supported, refuse that layer rather than certify
  * the home-only inventory. Ordinary unrelated project settings remain usable. */
-export declare function assertProjectDiscovery(agent: IntegrationAgent, directories: string[], home: string, canonical?: (path: string) => string): void;
+export declare function assertProjectDiscovery(agent: IntegrationAgent, directories: string[], home: string, canonical?: (path: string) => string, reviewed?: AgentDiscoveryBinding): void;
 /** Resolve configured plugin discovery without starting an agent or loading a plugin.
  * Unknown runtime registrations require explicit reviewed inputs, never a cache guess. */
 export declare function resolveAgentDiscovery(options: {

package/dist/lib/claude-marketplace-registry.d.ts

@@ -0,0 +1,17 @@
+export declare const CLAUDE_MARKETPLACE_REGISTRY_LIMITS: Readonly<{
+    bytes: number;
+    rows: 1024;
+    depth: 32;
+    nodes: 65536;
+    stringCharacters: 16384;
+    pathCharacters: 4096;
+}>;
+export interface ClaudeMarketplaceRegistryBudget {
+    remaining: number;
+}
+/** Capture explicitly reviewed registry structure; never infer this mode from a raw-byte witness. */
+export declare function captureClaudeMarketplaceRegistry(path: string, budget?: ClaudeMarketplaceRegistryBudget): {
+    path: string;
+    hashMode: "claude-marketplace-registry";
+    sha256: string;
+};

package/dist/lib/codex-hook-rpc.d.ts

@@ -0,0 +1,13 @@
+export declare const SUPPORTED_CODEX_HOOK_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.155.0"];
+export interface CodexHookRpc {
+    version: string;
+    processId?: number;
+    request(method: string, params: unknown): Promise<any>;
+    close(): Promise<void>;
+}
+/** An owned, short-lived native client. It cannot reload other app servers. */
+export declare function connectCodexHookRpc(options: {
+    command: string;
+    home: string;
+    codexHome: string;
+}): Promise<CodexHookRpc>;

package/dist/lib/codex-hook-trust-files.d.ts

@@ -0,0 +1,15 @@
+import { type BigIntStats } from "node:fs";
+export declare function need(value: unknown, code: string): asserts value;
+export declare function snapshot(file: string, privateFile?: boolean, options?: {
+    readOnlyPackage?: true;
+}): {
+    file: string;
+    privateFile: boolean;
+    readOnlyPackage: boolean;
+    text: string;
+    bytes: Buffer<ArrayBuffer>;
+    stat: BigIntStats;
+    sha256: string;
+};
+export declare function unchanged(before: ReturnType<typeof snapshot>): void;
+export declare function save(file: string, content: string | Buffer): void;

package/dist/lib/codex-hook-trust-identity.d.ts

@@ -0,0 +1,16 @@
+/** A private release adapter supplies a reviewed registry artifact identity;
+ * the normal CLI binds to its own installed entrypoint instead. */
+export interface ReviewedSkillsCli {
+    path: string;
+    version: string;
+    sha256: string;
+}
+export declare function bindSkillsCli(command: string, reviewed?: ReviewedSkillsCli): {
+    receipt: {
+        path: string;
+        version: string;
+        sha256: string;
+        manifestSha256: string;
+    };
+    recheck(): void;
+};

package/dist/lib/codex-hook-trust-layout.d.ts

@@ -0,0 +1,3 @@
+/** Conservative admission and text witness, never a TOML writer. Native Codex
+ * performs the versioned write; unrecognized inline/dotted trust shapes refuse. */
+export declare function codexTrustTextWitness(text: string, keys: string[]): string;

package/dist/lib/fleet-credentials.d.ts

@@ -147,6 +147,24 @@ export declare class SkillsFleetCredentialError extends Error {
  * on the error's NAME rather than on a class identity a bundle may not share.
  */
 export declare function isSkillsFleetCredentialError(error: unknown): error is SkillsFleetCredentialError;
+/**
+ * Translate the shared seam's `CredentialResolutionError` into this package's
+ * own refusal, or return null for anything else.
+ *
+ * A DELIBERATE selection that cannot be honoured — `HASNA_PROFILE` naming a
+ * profile that has no entry, an override or pointer that resolves to nothing, a
+ * corrupt credentials file — is thrown by `@hasna/contracts`, not by the
+ * transport resolver. Left untranslated it escaped every helper in this file:
+ * `skillsCredentialOrReason` and `resolveConfiguredRunRouting` recognise only
+ * `SkillsFleetCredentialError`, so a `--json` command or an MCP tool got an
+ * unhandled exception where the structured refusal was the whole point.
+ *
+ * The seam's message already names what was attempted and never carries a
+ * credential value. Pointer-completion messages can still carry the selected
+ * vault item identifier, so that exact identifier is removed before the error
+ * reaches any user-visible surface.
+ */
+export declare const REDACTED_VAULT_REFERENCE = "[redacted vault reference]";
 /**
  * Normalize a configured Skills authority to the origin the client dials.
  *

package/dist/lib/hook-diagnostics.d.ts

@@ -0,0 +1,7 @@
+export declare class HookDiagnosticError extends Error {
+    readonly code: string;
+    readonly stage: "context" | "sync";
+    constructor(code: string, stage: "context" | "sync");
+}
+export declare function hookChildError(stdout: string, stage: "context" | "sync"): HookDiagnosticError;
+export declare function hookFailureReason(error: unknown, profileId?: string): string;

package/dist/lib/plugin-admission.d.ts

@@ -0,0 +1,101 @@
+import { type ProfileClient } from "./profile-client.js";
+import { type SelectionCacheOptions } from "./selection-cache.js";
+import { type PluginFileWitness, type PluginProjectionManifest } from "./plugin-projection.js";
+import type { ResolvedSkillSelection } from "../types/skill-selection.js";
+/** Version 1 is certified against native Claude 2.1.274 and 2.1.276; new hosts require a contract revision/test. */
+export interface PluginAdmissionTarget {
+    schemaVersion: 1;
+    pluginId: string;
+    /** One marketplace command serves all explicitly reviewed native registration scopes. */
+    registrations: Array<{
+        scope: "user" | "project";
+        projectPath: string | null;
+    }>;
+    native: {
+        version: "2.1.274" | "2.1.276";
+        executable: string;
+        digest: string;
+    };
+    resolver: {
+        executable: string;
+        digest: string;
+    };
+}
+export interface PluginAdmissionBinding {
+    schemaVersion: 2;
+    authority: string;
+    workspaceId: string;
+    /** Stable account subject. Raw credential/key identities are never persisted. */
+    principal: PluginAdmissionPrincipal;
+    profileId: string;
+    bundleSlug: string;
+    target: PluginAdmissionTarget;
+}
+export type PluginBundleIdentity = Pick<ResolvedSkillSelection, "slug" | "version" | "bundleDigest">;
+export interface PluginAdmissionPrincipal {
+    userId: string;
+    accountId: string;
+    role: "owner";
+}
+export interface PluginRoutingIdentity extends PluginBundleIdentity {
+    aliases?: string[];
+    triggers?: {
+        keywords?: string[];
+        paths?: string[];
+        always?: boolean;
+    };
+}
+/** Every field that can route or activate the admitted plugin participates in approval. */
+export interface PluginAdmissionIdentity {
+    schemaVersion: 3;
+    binding: PluginAdmissionBinding;
+    bindingId: string;
+    profileRevision: string;
+    selection: PluginRoutingIdentity;
+    payloadSelections: PluginRoutingIdentity[];
+    manifest: PluginProjectionManifest;
+    originalTreeDigest: string;
+    projectionTreeDigest: string;
+    files: PluginFileWitness[];
+    removed: PluginFileWitness[];
+    sourceCommand: string;
+    /** Approved digest of the authenticated routing evidence snapshot. */
+    evidenceDigest: string;
+}
+export interface PluginAdmissionPlan extends PluginAdmissionIdentity {
+    observation: {
+        principal: PluginAdmissionPrincipal;
+        profileRevision: string;
+        integration: PluginRoutingIdentity;
+        payloads: PluginRoutingIdentity[];
+    };
+    planDigest: string;
+}
+export interface PluginAdmissionReceipt {
+    schemaVersion: 3;
+    plan: PluginAdmissionPlan;
+    materializedPath: string;
+    admittedAt: string;
+}
+/** Client/store injections are for embedding and isolated tests. The CLI exposes neither. */
+export interface PluginAdmissionOptions extends Pick<SelectionCacheOptions, "now"> {
+    client?: ProfileClient;
+    storeRoot?: string;
+    timeoutMs?: number;
+}
+export declare function pluginAdmissionRoot(): string;
+export declare function validatePluginTarget(value: unknown): asserts value is PluginAdmissionTarget;
+/** The accepted native command opens and hashes one inode, then executes that same descriptor. */
+export declare function pluginResolverCommand(binding: PluginAdmissionBinding): string;
+export declare function pluginBindingPath(storeRoot: string, id: string): string;
+export declare function pluginReceiptPath(storeRoot: string, id: string, digest: string): string;
+export declare function readPluginBinding(storeRoot: string, id: string): PluginAdmissionBinding;
+export declare function readPluginAdmissionReceipt(storeRoot: string, id: string, digest: string): PluginAdmissionReceipt;
+/** Command sources inherit an untrusted shell environment; authority comes from normal owner credentials. */
+export declare function assertPluginAuthorityEnvironment(env?: Record<string, string | undefined>): void;
+/** API reads only: a plan neither writes caches nor admits or executes package code. */
+export declare function planPluginAdmission(spec: string, profileId: string, target: PluginAdmissionTarget, options?: PluginAdmissionOptions): Promise<PluginAdmissionPlan>;
+/** Explicit local admission. Original archive and migrated payloads are already privately published. */
+export declare function admitPlugin(spec: string, profileId: string, target: PluginAdmissionTarget, approvedDigest: string, approvedEvidenceDigest: string, options?: PluginAdmissionOptions): Promise<PluginAdmissionReceipt>;
+/** Fresh authority on every invocation. No receipt, API failure or revocation ever returns a stale directory. */
+export declare function resolveAdmittedPlugin(id: string, options?: PluginAdmissionOptions): Promise<string>;

package/dist/lib/plugin-discovery.d.ts

@@ -0,0 +1,13 @@
+export interface ManagedPluginRegistrationWitness {
+    bindingId: string;
+    storeRoot: string;
+}
+export declare function validateManagedPluginWitnesses(value: unknown): asserts value is ManagedPluginRegistrationWitness[];
+/** This is a structured witness, not an exemption for a plugin ID or its cache directory. */
+export declare function hashManagedPluginRegistry(path: string, managed: ManagedPluginRegistrationWitness[]): string;
+export declare function captureManagedPluginRegistry(path: string, managedPlugins: ManagedPluginRegistrationWitness[]): {
+    path: string;
+    hashMode: "claude-plugin-registry";
+    managedPlugins: ManagedPluginRegistrationWitness[];
+    sha256: string;
+};

package/dist/lib/plugin-projection-store.d.ts

@@ -0,0 +1,14 @@
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import { type PluginFileWitness } from "./plugin-projection.js";
+/** Snapshot every file, rejecting empty directories and any membership or metadata change. */
+export declare function snapshotPluginTree(root: string, options?: {
+    nativeRuntime?: "claude-2.1.274" | "claude-2.1.276";
+}): SkillBundleEntry[];
+export declare function verifyPluginTree(root: string, witnesses: PluginFileWitness[]): void;
+/** Sibling staging and an exclusive, nonwaiting lock serialize cooperative publishers. */
+export declare function materializePluginTree(root: string, entries: SkillBundleEntry[]): void;
+export declare function readPluginJson(path: string): unknown | null;
+/** Atomic link publication never overwrites an existing receipt. */
+export declare function writePluginJsonImmutable(path: string, value: unknown): void;
+/** Hash the reviewed executable without executing it or allocating the entire binary. */
+export declare function pluginExecutableDigest(path: string): string;

package/dist/lib/plugin-projection.d.ts

@@ -0,0 +1,80 @@
+import type { SkillBundleEntry } from "./skill-bundle.js";
+import type { SkillSelection } from "../types/skill-selection.js";
+export declare const PLUGIN_PROJECTION_MANIFEST = "plugin-projection.json";
+export declare const PLUGIN_PROJECTION_LIMITS: Readonly<{
+    files: 1024;
+    bytes: number;
+    fileBytes: number;
+    metadataBytes: number;
+    registrations: 64;
+    history: 128;
+}>;
+export interface PluginPayloadMapping {
+    path: string;
+    kind: "skill" | "command";
+    /** Digest of the original one-file tree, including its path and mode. */
+    sourceDigest: string;
+    target: Pick<SkillSelection, "slug" | "version" | "bundleDigest">;
+}
+interface PluginProjectionFields {
+    agent: "claude";
+    pluginId: string;
+    payloads: PluginPayloadMapping[];
+}
+interface PluginUpstream {
+    source: string;
+    revision: string;
+    license: string;
+    treeDigest: string;
+}
+interface PluginReview {
+    hooks: "reviewed-no-skill-injection";
+    dependencies: "reviewed-no-retired-payload-dependency";
+}
+export type PluginProjectionManifest = PluginProjectionFields & ({
+    schemaVersion: 1;
+    upstream: PluginUpstream & {
+        version: string;
+    };
+    review: PluginReview;
+} | {
+    schemaVersion: 2;
+    upstream: PluginUpstream & {
+        version: string | null;
+    };
+    review: PluginReview & {
+        documentation: Array<{
+            path: string;
+            sourceDigest: string;
+        }>;
+    };
+});
+export interface PluginFileWitness {
+    path: string;
+    mode: number;
+    size: number;
+    sha256: string;
+}
+export interface PluginProjection {
+    manifest: PluginProjectionManifest;
+    payloads: PluginPayloadMapping[];
+    files: SkillBundleEntry[];
+    witnesses: PluginFileWitness[];
+    originalTreeDigest: string;
+    projectionTreeDigest: string;
+    removed: PluginFileWitness[];
+}
+export declare function pluginRefusal(message: string): never;
+export declare function pluginNeed(value: unknown, message: string): asserts value;
+export declare const pluginHash: (bytes: string | Uint8Array) => string;
+export declare function pluginObject(value: unknown): value is Record<string, unknown>;
+export declare function pluginKeys(value: unknown, keys: string[]): asserts value is Record<string, unknown>;
+export declare function pluginText(value: unknown, limit?: number): asserts value is string;
+export declare function pluginId(value: unknown): asserts value is string;
+export declare function pluginDigest(value: unknown): asserts value is string;
+export declare function validatePluginManifest(value: unknown): asserts value is PluginProjectionManifest;
+export declare function pluginFileWitnesses(entries: SkillBundleEntry[]): PluginFileWitness[];
+export declare function pluginTreeDigest(entries: SkillBundleEntry[]): string;
+/** Pure projection: no filesystem access, upstream commands, package installation or publication. */
+export declare function buildPluginProjection(entries: SkillBundleEntry[]): PluginProjection;
+export {};

package/dist/lib/profile-client.d.ts

@@ -1,18 +1,28 @@
 import type { ResolvedSkillProfile, StationSkillState, StationSkillStateInput } from "../types/skill-selection.js";
 export interface ProfileClient {
     readonly authority: string;
+    /** Stable whoami subject; raw credential/key identities are intentionally excluded. */
+    resolvePrincipal?(): Promise<AuthenticatedProfilePrincipal>;
     resolveProfile(id: string): Promise<ResolvedSkillProfile>;
     recordStation(id: string, state: StationSkillStateInput): Promise<StationSkillState>;
     getBundle(slug: string, version: string): Promise<Response | null>;
 }
+export type AuthenticatedProfileRole = "owner" | "admin" | "member" | "viewer";
+export interface AuthenticatedProfilePrincipal {
+    userId: string;
+    accountId: string;
+    role: AuthenticatedProfileRole;
+}
 export declare class HttpProfileClient implements ProfileClient {
     private key;
     readonly authority: string;
     private origin;
     constructor(key: string, origin: string);
+    private requestRoute;
     private request;
     private read;
     resolveProfile(id: string): Promise<ResolvedSkillProfile>;
+    resolvePrincipal(): Promise<AuthenticatedProfilePrincipal>;
     recordStation(id: string, input: StationSkillStateInput): Promise<StationSkillState>;
     getBundle(slug: string, version: string): Promise<Response | null>;
 }

package/dist/lib/recurring-recovery.d.ts

@@ -62,7 +62,7 @@ export declare function readRecurringRecovery(directory: string): {
         operation: "revoke";
         consentId: string;
     };
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     consentId: string | null;
 };
 export interface RecurringRecoveryOptions {
@@ -76,7 +76,7 @@ export declare function continueRecurringRecovery(customer: RecurringCustomer, d
     recoveryDirectory: string;
     operation: "activate" | "revoke";
     outcomeUnknown: boolean;
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     result: unknown;
 }>;
 export {};

package/dist/lib/recurring-surface.d.ts

@@ -219,7 +219,7 @@ export declare function executeRecurringSurface(action: RecurringSurfaceAction,
     recoveryDirectory: string;
     operation: "activate" | "revoke";
     outcomeUnknown: boolean;
-    phase: "pending" | "prepared" | "observed";
+    phase: "prepared" | "pending" | "observed";
     result: unknown;
 } | {
     cancelled: boolean;

package/dist/lib/remote-client.d.ts

@@ -7,8 +7,10 @@ import { type RemoteWorkspaceMemberErrorCode, type SetRemoteWorkspaceMemberRole,
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
 import { type RemoteCreditPack, type RemoteRunApproval, type RemoteRunQuote } from "./remote-account.js";
 import { type RemoteInputFile, type RemoteInputFileDescriptor } from "./remote-files.js";
+import { type RemoteCreditCheckout, type RemoteCreditCheckoutOptions, type RemoteCreditCheckoutErrorCode } from "./remote-credit-checkout.js";
 import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
 import { type RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
+import { type RemoteSkillsAccess } from "./remote-permissions.js";
 export type { RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
 /**
  * A server that predates this client's pin/tag/incremental-sync routes answered
@@ -28,6 +30,13 @@ export declare class RemoteRequestError extends Error {
     readonly status: number;
     constructor(path: string, status: number, _statusText?: string);
 }
+/** Bounded checkout outcome; the key is caller-owned, never copied from a server error. */
+export declare class RemoteCreditCheckoutError extends RemoteRequestError {
+    readonly code: RemoteCreditCheckoutErrorCode;
+    readonly requestIdempotencyKey: string;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(code: RemoteCreditCheckoutErrorCode, status: number, requestIdempotencyKey: string, retryAfterSeconds?: number | undefined);
+}
 /** A recognized unavailable quote; status compatibility and client-owned copy. */
 export declare class RemoteQuoteUnavailableError extends RemoteRequestError {
     readonly code: RemoteQuoteUnavailableCode;
@@ -123,7 +132,9 @@ export declare class RemoteSkillsClient {
     /** Low-level admission transport; interactive surfaces use submitQuotedRun. */
     submitRun(slug: string, input?: Record<string, unknown>, args?: string[], approval?: RemoteRunApproval): Promise<RemoteSkillRunContract>;
     quoteRun(slug: string, input?: Record<string, unknown>, args?: string[], files?: RemoteInputFileDescriptor[]): Promise<RemoteRunQuote>;
-    getCapabilities(): Promise<{
+    getCapabilities(options?: {
+        refresh?: boolean;
+    }): Promise<RemoteSkillsAccess & {
         contractVersion: 1;
         apiVersion: 1;
         capabilities: string[];
@@ -193,9 +204,8 @@ export declare class RemoteSkillsClient {
         formattedCreditBalance: string;
     }>;
     listCreditPacks(): Promise<RemoteCreditPack[]>;
-    createCreditCheckout(packId: string): Promise<{
-        url: string;
-    }>;
+    /** One checkout POST. Retain an explicit key before calling to recover even a lost process. */
+    createCreditCheckout(packId: string, options?: RemoteCreditCheckoutOptions): Promise<RemoteCreditCheckout>;
     getUsage(): Promise<Record<string, unknown>[]>;
     listInvoices(): Promise<Record<string, unknown>[]>;
     createBillingCheckout(): Promise<{

package/dist/lib/remote-credit-checkout.d.ts

@@ -0,0 +1,22 @@
+/** Caller-owned checkout identity. Reuse only for the same server, account and pack. */
+export interface RemoteCreditCheckoutOptions {
+    idempotencyKey?: string;
+}
+export interface RemoteCreditCheckout {
+    url: string;
+    requestIdempotencyKey: string;
+}
+export declare const creditCheckoutKeyPattern: RegExp;
+export declare function creditCheckoutRequestKey(value: unknown): string;
+export declare const creditCheckoutMessages: {
+    readonly CREDIT_CHECKOUT_UNCONFIRMED: "Checkout creation could not be confirmed. Keep the request idempotency key, inspect billing, and use the same key for an explicit retry on the same server, account and pack. No automatic retry was made.";
+    readonly CREDIT_CHECKOUT_IN_PROGRESS: "This checkout is still being created. Wait before explicitly retrying the same server, account and pack with the same request idempotency key. No automatic retry was made.";
+    readonly CREDIT_CHECKOUT_EXPIRED: "This checkout has expired. Inspect billing before deliberately starting a new purchase with a new request idempotency key. Do not retry this checkout automatically.";
+    readonly CREDIT_CHECKOUT_FULFILLED: "This checkout is already fulfilled. Inspect the account balance; do not create another checkout to recover this purchase.";
+};
+export type RemoteCreditCheckoutErrorCode = keyof typeof creditCheckoutMessages;
+/** Only recognized server states become typed outcomes; never retain server text. */
+export declare function creditCheckoutFailure(value: unknown, status: number, key: string): {
+    code: RemoteCreditCheckoutErrorCode;
+    retryAfterSeconds?: number;
+};

package/dist/lib/remote-customer-operations.d.ts

@@ -1,3 +1,4 @@
+import type { RemoteCreditCheckoutOptions } from "./remote-credit-checkout.js";
 import type { RemoteSkillsClient } from "./remote-client.js";
 /** Shared customer operation declarations for MCP registration and its discovery contract. */
 export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
@@ -11,7 +12,7 @@ export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
     readonly title: "Get Server Capabilities";
     readonly parameter: null;
     readonly mutates: false;
-    readonly invoke: (client: RemoteSkillsClient) => Promise<{
+    readonly invoke: (client: RemoteSkillsClient) => Promise<import("./remote-permissions.js").RemoteSkillsAccess & {
         contractVersion: 1;
         apiVersion: 1;
         capabilities: string[];
@@ -49,9 +50,7 @@ export declare const REMOTE_CUSTOMER_OPERATIONS: readonly [{
     readonly title: "Create Credit Checkout";
     readonly parameter: "pack_id";
     readonly mutates: true;
-    readonly invoke: (client: RemoteSkillsClient, value: string) => Promise<{
-        url: string;
-    }>;
+    readonly invoke: (client: RemoteSkillsClient, value: string, options?: RemoteCreditCheckoutOptions) => Promise<import("./remote-credit-checkout.js").RemoteCreditCheckout>;
 }, {
     readonly name: "get_billing_usage";
     readonly title: "Get Billing Usage";

package/dist/lib/remote-permissions.d.ts

@@ -0,0 +1,24 @@
+/** Effective access belongs to the credential, independently of workspace role. */
+export interface RemoteSkillsPermissions {
+    read?: boolean;
+    publish?: boolean;
+    profilesWrite?: boolean;
+    stationStateWrite?: boolean;
+    cloudSubmit?: boolean;
+    executionGrantsRead?: boolean;
+    executionGrantsWrite?: boolean;
+    executionGrantsResolve?: boolean;
+}
+export interface RemoteSkillsAccess {
+    scopes?: string[];
+    permissions?: RemoteSkillsPermissions;
+}
+/** Pick known fields only; never reflect additive provider fields into diagnostics. */
+export declare function parseSkillsAccess(value: unknown): RemoteSkillsAccess;
+export declare class RemoteSkillsPermissionError extends Error {
+    readonly permission: "publish" | "profilesWrite";
+    readonly code = "SKILLS_PERMISSION_DENIED";
+    readonly status = 403;
+    constructor(permission: "publish" | "profilesWrite");
+}
+export declare function assertSkillsPermission(access: RemoteSkillsAccess, permission: "publish" | "profilesWrite"): void;

package/dist/lib/selection-cache.d.ts

@@ -13,9 +13,28 @@ export interface CachedSelectionProfile {
     verifiedAt: string;
     profile: ResolvedSkillProfile;
 }
+export interface SkillSessionParentBinding {
+    sessionId: string;
+    generation: number;
+    receiptSha256: string;
+}
 export interface SkillSessionReceipt extends CachedSelectionProfile {
     sessionId: string;
     loaded: string[];
+    /** Monotonic across sanctioned receipt writes. Legacy receipts without it are generation zero. */
+    generation?: number;
+    /** Private local metadata binding a child receipt to the exact parent snapshot it inherited. */
+    parent?: SkillSessionParentBinding;
+}
+export interface SkillSessionSnapshot extends SkillSessionParentBinding {
+    path: string;
+    bytes: Uint8Array;
+    receipt: SkillSessionReceipt;
+    sha256: string;
+}
+export interface SkillSessionWritePrecondition {
+    current: SkillSessionParentBinding | null;
+    parent?: SkillSessionParentBinding;
 }
 export declare const MAX_CACHED_PROFILE_AGE_MS: number;
 export declare const SELECTION_LOCK_FILE = "selection.lock.json";
@@ -38,3 +57,16 @@ export declare function projectSelectionLockPath(projectDir: string): string;
 export declare function readProjectSelection(projectDir: string): CachedSelectionProfile | null;
 export declare function sessionReceiptPath(sessionId: string, options?: SelectionCacheOptions): string;
 export declare function readSkillSession(sessionId: string, options?: SelectionCacheOptions): SkillSessionReceipt | null;
+export declare function readSkillSessionSnapshotIfExists(sessionId: string, options?: SelectionCacheOptions): SkillSessionSnapshot | null;
+export declare function readSkillSessionSnapshot(sessionId: string, options?: SelectionCacheOptions): SkillSessionSnapshot;
+export declare function skillSessionSnapshotBinding(snapshot: SkillSessionSnapshot): SkillSessionParentBinding;
+export declare function nextSkillSessionGeneration(generation: number): number;
+/** Receipt creation and updates are exact-snapshot CAS operations. Child creation also fences its parent. */
+export declare function writeSkillSession(receipt: SkillSessionReceipt, expected: SkillSessionWritePrecondition, options?: SelectionCacheOptions): void;
+/** Preserve both sides before the single atomic replacement; failures retain recovery evidence. */
+export declare function replaceSkillSession(expected: SkillSessionParentBinding, replacement: SkillSessionReceipt, plan: unknown, options?: SelectionCacheOptions, beforeCommit?: () => void): {
+    archivePath: string;
+    receiptPath: string;
+    beforeSha256: string;
+    afterSha256: string;
+};

package/dist/lib/selection-resolver.d.ts

@@ -2,7 +2,7 @@
 import { type ProfileClient } from "./profile-client.js";
 import type { ResolvedSkillProfile, ResolvedSkillSelection } from "../types/skill-selection.js";
 import type { SkillBundleEntry } from "./skill-bundle.js";
-import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionReceipt } from "./selection-cache.js";
+import { type CachedSelectionProfile, type SelectionCacheOptions, type SkillSessionParentBinding, type SkillSessionReceipt } from "./selection-cache.js";
 export interface SelectionResolverOptions extends SelectionCacheOptions {
     client?: ProfileClient;
     cached?: boolean;
@@ -31,6 +31,8 @@ export declare function syncSelectionProfile(profileId: string, options?: SyncSe
 export interface ResolvedSelectionContext {
     receipt: CachedSelectionProfile;
     session: SkillSessionReceipt | null;
+    sessionSnapshot: SkillSessionParentBinding | null;
+    parentSnapshot?: SkillSessionParentBinding;
     inheritedLoaded?: string[];
     client?: ProfileClient;
 }