@hasna/skills 0.10.72 → 0.10.74

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

@@ -1,6 +1,7 @@
 import type { IntegrationAgent } from "./agent-adapters.js";
 import { type DiscoveryDirectory } from "./agent-discovery-directories.js";
 import { type CodexReviewedHookSource } from "./codex-hook-mcp-dependencies.js";
+import { CLAUDE_ORPHAN_MARKER_MODE } from "./claude-plugin-cache-marker.js";
 import { type NativeDiscoveryWitnessTolerance } from "./native-discovery-witness-change.js";
 import { type ManagedPluginRegistrationWitness } from "./plugin-discovery.js";
 import { type CodexHookDiscoveryRecovery } from "./codex-hook-discovery-recovery.js";
@@ -95,6 +96,11 @@ export declare function projectNativeDiscoveryFields(text: string, format: "json
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;
+/** The witness class that may keep its reviewed digest beneath a positively
+ * verified absent root: a full byte witness, the installer's full manifest
+ * projection or a present version-root orphan marker. Null for every other
+ * source, which must stay current. */
+export type RetainedAbsentWitness = "bytes" | "claude-plugin-manifest-v1" | typeof CLAUDE_ORPHAN_MARKER_MODE;
 /** Only native capability locations covered by the complete typed cache census
  * qualify. Historical sources remain stored; arbitrary missing files do not. */
 export declare function codexSemanticCacheSourceRole(source: DiscoverySource, cacheRoot: string, parents: readonly string[], hookParents?: readonly string[]): boolean;
@@ -109,6 +115,25 @@ export declare function verifyAgentDiscovery(binding: AgentDiscoveryBinding, cod
     alias: string;
     target: string;
 }[], witnessTolerance?: NativeDiscoveryWitnessTolerance): void;
+/** One stored Claude discovery source as an installer sees it. */
+export type ClaudeDiscoverySourceVerdict = {
+    status: "current";
+} | {
+    status: "retained-absent";
+    root: string;
+    witness: RetainedAbsentWitness;
+} | {
+    status: "drift";
+    reason: "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+};
+/** Read-only, per-source report on a stored Claude discovery binding, in
+ * stored order. A source is retained only through the same absent retired
+ * version rule and predicate verifyAgentDiscovery applies; a refused rule
+ * retains nothing. Every other source is checked by its own witness, exactly
+ * as verification checks it (a typed orphan marker by the marker predicate).
+ * This report never accepts a binding by itself: a caller must also require
+ * verifyAgentDiscovery to accept the same binding. */
+export declare function classifyClaudeDiscoverySources(binding: AgentDiscoveryBinding): ClaudeDiscoverySourceVerdict[];
 export declare function rebindAgentDiscovery(binding: AgentDiscoveryBinding, changes: Map<string, string>): AgentDiscoveryBinding;
 /** Explicit streaming integrity witness. Never read an executable as text or execute it. */
 export declare function captureDiscoveryExecutableSources(paths: string[]): DiscoverySource[];
@@ -116,6 +141,11 @@ export declare function captureDiscoveryExecutableSources(paths: string[]): Disc
 export declare function captureDiscoveryByteSources(paths: string[]): DiscoverySource[];
 /** Capture executable/source path identity, including links and absent targets. */
 export declare function captureDiscoveryPathSources(paths: string[]): DiscoverySource[];
+/** Top-level keys whose presence, at any value, makes a project Claude settings
+ * file a higher-precedence discovery source that needs review. Claude 2.1.300
+ * rewrites `additionalMarketplaces` into `extraKnownMarketplaces` on every
+ * settings read, including local settings, so the alias counts as well. */
+export declare const CLAUDE_PROJECT_DISCOVERY_KEYS: readonly ["enabledPlugins", "extraKnownMarketplaces", "additionalMarketplaces", "skillOverrides"];
 /** 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. */
@@ -143,6 +173,12 @@ export declare function verifyAutomaticDiscoveryClosure(binding: AgentDiscoveryB
  * the stored digest. Witness modes
  * without a replacement digest (V6, artifacts, managed registries) stay strict. */
 export declare function codexVendorConfigChangeOnly(source: DiscoverySource, cache: string): boolean;
+/** Whether replacing `path` with `text` leaves every recorded witness of it
+ * satisfied, judged by each source's own digest mode without touching the file,
+ * with the same screen-reader receipt tolerance typed V1-V5 verification applies.
+ * Fails closed: a review artifact, managed-plugin or hook-source witness, a
+ * semantic cache binding of the file, or an unsupported mode counts as changed. */
+export declare function discoveryTextKeepsWitness(binding: Pick<AgentDiscoveryBinding, "sources" | "codexSemanticCache">, path: string, text: string): boolean;
 /** `executable` is the agent's runtime: omitted, it is resolved through PATH;
  * a value (or null for none) is used as given, so verification never depends
  * on the caller's PATH. */

package/dist/lib/claude-installer-binding.d.ts

@@ -0,0 +1,65 @@
+import { type RetainedAbsentWitness } from "./agent-discovery.js";
+export declare const CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA: "skills.claude-discovery-binding-verification/v1";
+/** The rule that lets a stored witness stay unverified because Claude removed
+ * its whole retired plugin-cache version while unchanged settings and
+ * registrations select a current sibling version. */
+export declare const ABSENT_RETIRED_CLAUDE_VERSION_RULE: "absent-retired-claude-version";
+export type ClaudeDiscoveryBindingRefusalCode = "POLICY_PATH_MISMATCH" | "POLICY_UNAVAILABLE" | "POLICY_UNREADABLE" | "BINDING_UNAVAILABLE" | "BINDING_INVALID" | "POLICY_CHANGED";
+/** A request, policy or stored-binding read/parse failure: no verdict. */
+export declare class ClaudeDiscoveryBindingRefusal extends Error {
+    readonly code: ClaudeDiscoveryBindingRefusalCode;
+    constructor(code: ClaudeDiscoveryBindingRefusalCode);
+}
+export type ClaudeBindingSourceFailure = "MISSING" | "APPEARED" | "CHANGED" | "MARKER_INVALID" | "REFUSED";
+export type ClaudeBindingDirectoryFailure = "MEMBERSHIP_CHANGED" | "REFUSED";
+export interface ClaudeBindingSourceReport {
+    index: number;
+    path: string;
+    hashMode: string | null;
+    format: string | null;
+    sha256: string | null;
+    status: "current" | "retained-absent" | "drift";
+    retention?: {
+        rule: typeof ABSENT_RETIRED_CLAUDE_VERSION_RULE;
+        root: string;
+        witness: RetainedAbsentWitness;
+    };
+    reason?: ClaudeBindingSourceFailure;
+}
+export interface ClaudeBindingDirectoryReport {
+    index: number;
+    path: string;
+    status: "current" | "drift";
+    reason?: ClaudeBindingDirectoryFailure;
+}
+export type ClaudeBindingFailure = {
+    kind: "source";
+    index: number;
+    path: string;
+    reason: ClaudeBindingSourceFailure;
+} | {
+    kind: "directory";
+    index: number;
+    path: string;
+    reason: ClaudeBindingDirectoryFailure;
+} | {
+    kind: "binding";
+    reason: "DISCOVERY_REFUSED";
+};
+export interface ClaudeDiscoveryBindingVerification {
+    schema: typeof CLAUDE_DISCOVERY_BINDING_VERIFICATION_SCHEMA;
+    ok: boolean;
+    policySha256: string;
+    discoverySha256: string;
+    agent: "claude";
+    method: "reviewed" | "automatic";
+    rootCount: number;
+    sources: ClaudeBindingSourceReport[];
+    directories: ClaudeBindingDirectoryReport[];
+    failures: ClaudeBindingFailure[];
+}
+/** Verify the stored `bridge.discovery.claude` binding of the package-owned
+ * Skills policy. `ok` is true only when the hook's own discovery verification
+ * accepts the binding and every source is current or retained under the
+ * absent retired version rule, and every directory witness is current. */
+export declare function verifyClaudeInstallerDiscoveryBinding(policyPath: string): ClaudeDiscoveryBindingVerification;

package/dist/lib/codex-node-modules.d.ts

@@ -0,0 +1,11 @@
+/** Whether Codex can load a skill below `path`, a `node_modules` directory
+ * `depth` levels below its plugin cache. A marketplace, plugin or version
+ * directory is an identity, so one named `node_modules` is always walked.
+ * Inside a version, the directory is walked when it lies in, or leads to, a
+ * manifest-declared skills path or the default `skills` root. Codex replaces
+ * the default with a declared path; Skills keeps walking it, as it walks every
+ * other visible directory in the cache. A manifest that cannot be read exactly
+ * (a link or special file, oversized, invalid UTF-8 or JSON, duplicate keys, an
+ * unsupported skills shape or an escaping path) walks it too, so an unreadable
+ * declaration never hides a loaded skill. */
+export declare function codexPluginCacheSkillTree(path: string, depth: number): boolean;

package/dist/lib/codex-settings-witness-v1.d.ts

@@ -1,5 +1,14 @@
 import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
 export declare function hashCodexSettingsReplacement(text: string, budget?: ClaudeSettingsWitnessBudget): string;
+/** The parsed document and numeric spellings a V1 digest binds, before the
+ * documented inference fields are removed. Callers that edit the structure
+ * (codexSettingsToleratesScreenReaderReceipt) finish each edited copy separately. */
+export declare function prepareCodexSettingsV1(text: string): {
+    config: Record<string, any>;
+    tokens: string[];
+};
+/** The V1 digest of a prepared structure. Mutates `config`. */
+export declare function finishCodexSettingsV1(config: Record<string, any>, tokens: string[]): string;
 export declare function captureCodexSettings(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;
     hashMode: "codex-settings-v1";

package/dist/lib/codex-settings-witness.d.ts

@@ -5,6 +5,24 @@ import { type ClaudeSettingsWitnessBudget } from "./claude-settings-witness.js";
  * `codex-settings-v2` witness binds strictly more of the same file, so it
  * supersedes this projection instead of coexisting with it. */
 export declare const CODEX_DISCOVERY_PROJECTION_FIELDS: readonly ["plugins", "marketplaces", "skills"];
+/** Typed modes whose digests bind the receipt. */
+export type CodexReceiptSettingsMode = "codex-settings-v1" | "codex-settings-v2" | "codex-settings-v3" | "codex-settings-v4" | "codex-settings-v5";
+/** How a current document relates to a typed V1-V5 witness's reviewed digest.
+ * `screen-reader-receipt` is the only tolerated difference. */
+export type CodexSettingsWitnessMatch = "exact" | "screen-reader-receipt";
+/** True when `text` differs from the document a typed V1-V5 witness reviewed
+ * only by the boolean screen-reader receipt, proven by reproducing `expected`
+ * under the witness's own unchanged digest from the current document with the
+ * receipt edited back. The text-bound projections (local MCP rows, V4 counts,
+ * numeric spelling) run once on the current text; a receipt line holds no
+ * numeric token. Digest values never change and nothing is recorded. Any other
+ * TUI key, a non-boolean value and every other difference stay bound.
+ * Fail-closed: errors return false. */
+export declare function codexSettingsToleratesScreenReaderReceipt(text: string, hashMode: CodexReceiptSettingsMode, expected: string): boolean;
+/** Read a typed V1-V5 settings witness file once and classify it against the
+ * reviewed digest: `exact`, `screen-reader-receipt` (the only tolerated
+ * difference), or null (drift). */
+export declare function codexSettingsWitnessMatch(path: string, hashMode: CodexReceiptSettingsMode, expected: string, budget?: ClaudeSettingsWitnessBudget): CodexSettingsWitnessMatch | null;
 export declare function hashCodexSettingsReplacementV2(text: string, budget?: ClaudeSettingsWitnessBudget): string;
 export declare function captureCodexSettingsV2(path: string, budget?: ClaudeSettingsWitnessBudget): {
     path: string;

package/dist/lib/portable-skills-files.d.ts

@@ -52,6 +52,16 @@ export declare function ensurePortableSkillFiles(skillPath: string, manifest: Po
  * locally, so `port` must never fabricate executable stubs (package.json, bin,
  * src/index.ts, tsconfig.json, AGENTS.md). Apart from aligning declared names
  * after an import rename, it preserves the copied prose and metadata.
+ *
+ * "Metadata" includes what the candidate declared in skill.json. An instruction
+ * skill may legitimately bundle a helper command (and inputs for it) — the
+ * validator permits a package.json bin on an instruction skill for exactly that
+ * reason — so declared `commands` and `inputs` are carried through verbatim and
+ * only an absent declaration becomes an explicit empty array. Forcing them to []
+ * here silently erased the declaration on disk: writeSkillJsonWithHash() merges
+ * the rebuilt manifest over the copied candidate skill.json, so the candidate's
+ * own array was destroyed and the manifest was left self-inconsistent
+ * (runtime.entrypoint still naming an entry no command declared).
  */
 export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function copySkillDirectory(source: string, destination: string): void;

package/dist/lib/selected-run.d.ts

@@ -13,6 +13,50 @@ export interface ResolvedSelectedRun {
     cacheDir: string;
 }
 export declare function resolveSelectedRun(spec: string, profileId: string, options?: SelectionResolverOptions): Promise<ResolvedSelectedRun>;
+/**
+ * The operation an instruction skill declares, if it declares one.
+ *
+ * An instruction skill is prose-first: agents follow SKILL.md, and `skills run`
+ * refuses it. Its manifest may still declare the one operation it ships — the
+ * first `commands` entry, naming the helper — together with an explicit runtime
+ * contract in `runtime` (`runtime` plus its `version`/`timeout` policy). Such a
+ * skill is runnable through that declared operation, and only through it: the
+ * executed file is exactly the entry the selected command declares, it must be a
+ * regular file in the selected bundle, and a `runtime.entrypoint` that disagrees
+ * with it is an inconsistent declaration that refuses (see
+ * {@link instructionEntrypointMismatch}) rather than quietly running the other
+ * file. An instruction skill that declares no operation — no command, a
+ * non-string or empty entry, or no runtime contract — keeps the prose-only
+ * refusal (`skills load`, never `skills run`), so an instruction bundle is never
+ * mistaken for a runnable stub.
+ */
+export declare function declaredOperation(manifest: Record<string, any>): {
+    entry: string;
+} | null;
+/**
+ * The entry the instruction skill's declared command names, when it names one.
+ * The first `commands` entry is the operation: nothing else in the manifest
+ * selects what an instruction skill runs.
+ */
+export declare function instructionCommandEntry(manifest: Record<string, any>): string | null;
+/**
+ * A declared `runtime.entrypoint` that disagrees with the declared command entry,
+ * for an instruction skill. The command entry is the authority, so a disagreement
+ * is an inconsistent declaration: it refuses, and the disagreeing file never runs.
+ */
+export declare function instructionEntrypointMismatch(manifest: Record<string, any>): string | null;
+/**
+ * Why an instruction skill cannot run locally, if it cannot. `isBundledFile` says
+ * whether a path is a regular file in the selected bundle, so a declared command
+ * entry that is not there is refused by name instead of being substituted. The
+ * CLI, the MCP tool and the local executor all ask this one function, so the
+ * reason and the code cannot drift between them. A runnable instruction skill
+ * (declared command, agreeing runtime, entry present in the bundle) returns null.
+ */
+export declare function instructionRunRefusal(manifest: Record<string, any>, isBundledFile: (path: string) => boolean): {
+    code: string;
+    message: string;
+} | null;
 export interface SelectedLocalRunOptions {
     args?: string[];
     input?: unknown;
@@ -54,6 +98,7 @@ export declare function executeSelectedLocal(selected: ResolvedSelectedRun, opti
     selection: ResolvedSkillSelection;
     target: "local";
     runtime: any;
+    entrypoint: string;
     inputDigest: string;
     runDirectory: string;
 }>;

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

@@ -0,0 +1,108 @@
+import { type SelectionCacheOptions } from "./selection-cache.js";
+/** Bounded so one receipt can never carry an unbounded drift list. */
+export declare const PROVENANCE_DRIFT_LIMIT = 200;
+export type SelectionProvenanceStatus = "current" | "behind" | "pinned" | "unverified";
+export type SelectionProvenanceSource = "local-receipt" | "authority-receipt" | "session-receipt";
+export type SelectionProvenanceReference = "authority" | "synced-snapshot" | "unavailable";
+/**
+ * The fixed diagnostic vocabulary. A reader's exception text is never carried,
+ * only one of these codes, so a foreign body or a credential inside an error
+ * string cannot reach a receipt that may be shared.
+ */
+export type SelectionProvenanceReason = "CURRENT_SCHEMA_MATCH" | "REVISION_BEHIND" | "PINNED_BY_DESIGN" | "IDENTITY_MISMATCH" | "INCOMPLETE_RECEIPT" | "DIFFERENT_PROFILE" | "NO_LOCAL_RECEIPT" | "NO_SESSION_NAMED" | "NO_SESSION_RECEIPT" | "NO_STATION_RECEIPT" | "READ_REFUSED" | "REFERENCE_FROM_AUTHORITY" | "REFERENCE_NOT_AUTHORITY" | "REFERENCE_UNAVAILABLE" | "NO_STATION_REPORTED";
+export interface SelectionProvenanceVersion {
+    slug: string;
+    version: string;
+    bundleDigest?: string;
+}
+export interface SelectionProvenanceConsumer {
+    kind: "station" | "session";
+    source: SelectionProvenanceSource;
+    /** The local host for a local receipt, the requested station only for the authority receipt. */
+    id: string;
+    /** Whether `id` names the host running this command or a station named on the command line. */
+    idKind: "local-host" | "requested-station";
+    profileId?: string;
+    profileRevision?: string;
+    /** Compared, never assumed: a matching revision under another identity is not current. */
+    authority?: string;
+    workspaceId?: string;
+    observedAt?: string;
+    selectionCount?: number;
+    /** Only for a session: how many of its selections it really loaded. */
+    loadedCount?: number;
+    /** Only for a session: the exact versions it really loaded. */
+    consumed?: SelectionProvenanceVersion[];
+    status: SelectionProvenanceStatus;
+    reasonCode: SelectionProvenanceReason;
+    reason: string;
+}
+export interface SelectionProvenanceDrift {
+    source: SelectionProvenanceSource;
+    id: string;
+    slug: string;
+    selectedVersion: string;
+    observedVersion: string;
+}
+export interface SelectionProvenanceReceipt {
+    schemaVersion: 1;
+    readOnly: true;
+    selectionProfile: string;
+    selected: {
+        profileId: string;
+        profileRevision?: string;
+        selectionCount?: number;
+        authority?: string;
+        workspaceId?: string;
+        source: SelectionProvenanceReference;
+        observedAt?: string;
+        reasonCode: SelectionProvenanceReason;
+        reason: string;
+    };
+    consumers: SelectionProvenanceConsumer[];
+    drift: SelectionProvenanceDrift[];
+    driftTruncated: boolean;
+    /**
+     * What this receipt deliberately does not attest. Version and digest evidence
+     * for published payloads, native discovery, native locks and live consumer
+     * adoption are outside this command and stay unverified here rather than being
+     * implied by a clean-looking result.
+     */
+    notAttested: string[];
+}
+export interface SelectionProvenanceInput {
+    profileId: string;
+    /** The station whose authority-held sync receipt is read. */
+    stationId: string;
+    /** The host this command runs on. Never conflated with `stationId`. */
+    localStationId: string;
+    sessionId?: string;
+    /** Read the reference from the locally synced snapshot; never ask the authority. */
+    cached?: boolean;
+}
+/** A station receipt reduced to what this receipt compares. */
+export interface ProvenanceStationObservation {
+    profileId: string;
+    profileRevision: string;
+    appliedAt: string;
+    workspaceId?: string;
+    selections: readonly {
+        slug: string;
+        version: string;
+    }[];
+}
+export interface SelectionProvenanceOptions extends SelectionCacheOptions {
+    /** Injected by the SDK and tests; defaults to the authenticated reads. */
+    readSelected?: (profileId: string) => Promise<{
+        profileId: string;
+        profileRevision: string;
+        authority?: string;
+        workspaceId?: string;
+        selections: readonly {
+            slug: string;
+            version: string;
+        }[];
+    }>;
+    readStation?: (stationId: string) => Promise<ProvenanceStationObservation>;
+}
+export declare function readSelectionProvenance(input: SelectionProvenanceInput, options?: SelectionProvenanceOptions): Promise<SelectionProvenanceReceipt>;

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.72";
+var version = "0.10.74";
 var package_default = {
   name: "@hasna/skills",
   version,