@hasna/skills 0.10.72 → 0.10.74

package/bin/mcp.js

@@ -23,7 +23,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.72",
+    version: "0.10.74",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -22021,8 +22021,8 @@ function ensureInstructionSkillFiles(skillPath, manifest) {
     displayName: manifest.displayName ?? displayName(manifest.name),
     category: manifest.category ?? "Development Tools",
     tags: manifest.tags?.length ? manifest.tags : ["custom", manifest.name],
-    inputs: [],
-    commands: []
+    inputs: Array.isArray(manifest.inputs) ? manifest.inputs : [],
+    commands: Array.isArray(manifest.commands) ? manifest.commands : []
   };
   if (!existsSync6(join9(skillPath, "SKILL.md"))) {
     writeFileSync2(join9(skillPath, "SKILL.md"), renderSkillMd(next));
@@ -32219,6 +32219,10 @@ function canonical4(value, depth = 0, budget2 = { remaining: 65536 }) {
 function hashCodexSettingsReplacement(text2, budget2 = { remaining: 256 * 1024 * 1024 }) {
   need4(Buffer.byteLength(text2) <= 1024 * 1024 && budget2.remaining >= Buffer.byteLength(text2));
   budget2.remaining -= Buffer.byteLength(text2);
+  const prepared = prepareCodexSettingsV1(text2);
+  return finishCodexSettingsV1(prepared.config, prepared.tokens);
+}
+function prepareCodexSettingsV1(text2) {
   let config2;
   try {
     config2 = Bun.TOML.parse(text2);
@@ -32226,6 +32230,9 @@ function hashCodexSettingsReplacement(text2, budget2 = { remaining: 256 * 1024 *
     throw new Error("Invalid Codex settings witness");
   }
   need4(config2 && typeof config2 === "object" && !Array.isArray(config2));
+  return { config: config2, tokens: numericTokens(text2) };
+}
+function finishCodexSettingsV1(config2, tokens) {
   if (Object.hasOwn(config2, "model")) {
     need4(typeof config2.model === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(config2.model));
     delete config2.model;
@@ -32235,11 +32242,7 @@ function hashCodexSettingsReplacement(text2, budget2 = { remaining: 256 * 1024 *
       need4(typeof config2[key] === "string" && values.has(config2[key]));
       delete config2[key];
     }
-  return sha(`hasna.skills.codex-settings.v1\x00${JSON.stringify([canonical4(config2), numericTokens(text2)])}`);
-}
-function captureCodexSettings(path, budget2 = { remaining: 256 * 1024 * 1024 }) {
-  const text2 = readNativeSettingsWitnessFile(path, budget2, "config.toml");
-  return { path, hashMode: "codex-settings-v1", sha256: hashCodexSettingsReplacement(text2) };
+  return sha(`hasna.skills.codex-settings.v1\x00${JSON.stringify([canonical4(config2), tokens])}`);
 }
 var sha = (text2) => createHash11("sha256").update(text2).digest("hex"), EFFORT, VERBOSITY;
 var init_codex_settings_witness_v1 = __esm(() => {
@@ -32953,7 +32956,7 @@ function projectStatusLine(config2) {
   if (!Object.keys(tui).length)
     delete config2.tui;
 }
-function settingsDigest2(text2, version2 = 2, dependencies) {
+function prepareSettings(text2, version2, dependencies) {
   let config2;
   try {
     config2 = Bun.TOML.parse(text2);
@@ -32992,51 +32995,106 @@ function settingsDigest2(text2, version2 = 2, dependencies) {
       delete config2.tui.model_availability_nux;
     if (isRecord3(config2.tui) && typeof config2.tui.screen_reader_detection_done === "boolean")
       delete config2.tui.screen_reader_detection_done;
-    config2 = embedCodexNumericTokens(config2, tokens);
+    return { config: embedCodexNumericTokens(config2, tokens), numericSource: text2, dependencies };
+  }
+  const mcp = version2 >= 3 ? projectRegularCodexMcp(config2, text2) : { config: config2, numericSource: text2 };
+  return version2 >= 4 ? projectModelAvailabilityNux(mcp.config, mcp.numericSource) : mcp;
+}
+function finishSettings(prepared, version2) {
+  const config2 = prepared.config;
+  if (version2 === 6) {
     normalize2(config2, 6);
     if (isRecord3(config2.tui) && !Object.keys(config2.tui).length)
       delete config2.tui;
-    return sha2(`hasna.skills.codex-settings.v6\x00${JSON.stringify([canonical5(config2), canonical5(dependencies)])}`);
+    return sha2(`hasna.skills.codex-settings.v6\x00${JSON.stringify([canonical5(config2), canonical5(prepared.dependencies)])}`);
   }
-  const mcp = version2 >= 3 ? projectRegularCodexMcp(config2, text2) : { config: config2, numericSource: text2 };
-  const projected = version2 >= 4 ? projectModelAvailabilityNux(mcp.config, mcp.numericSource) : mcp;
-  normalize2(projected.config, version2);
-  const values = [canonical5(projected.config), numericTokens2(projected.numericSource)];
+  normalize2(config2, version2);
+  const values = [canonical5(config2), numericTokens2(prepared.numericSource)];
   return sha2(`hasna.skills.codex-settings.v${version2}\x00${JSON.stringify(values)}`);
 }
+function settingsDigest2(text2, version2 = 2, dependencies) {
+  return finishSettings(prepareSettings(text2, version2, dependencies), version2);
+}
+function cloneTree(value) {
+  if (Array.isArray(value))
+    return value.map(cloneTree);
+  if (isRecord3(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    return Object.fromEntries(Object.entries(value).map(([key2, child2]) => [key2, cloneTree(child2)]));
+  return value;
+}
+function receiptEdits(config2) {
+  const tui = config2.tui;
+  const set2 = (value) => (target) => {
+    if (!isRecord3(target.tui))
+      target.tui = {};
+    target.tui[SCREEN_READER_RECEIPT] = value;
+  };
+  if (tui === undefined || isRecord3(tui) && !Object.hasOwn(tui, SCREEN_READER_RECEIPT))
+    return [set2(true), set2(false)];
+  if (!isRecord3(tui) || typeof tui[SCREEN_READER_RECEIPT] !== "boolean")
+    return [];
+  const remove = (dropEmpty) => (target) => {
+    delete target.tui[SCREEN_READER_RECEIPT];
+    if (dropEmpty && !Object.keys(target.tui).length)
+      delete target.tui;
+  };
+  return [remove(true), ...Object.keys(tui).length === 1 ? [remove(false)] : [], set2(!tui[SCREEN_READER_RECEIPT])];
+}
+function codexSettingsToleratesScreenReaderReceipt(text2, hashMode, expected) {
+  try {
+    if (Buffer.byteLength(text2) > 1024 * 1024 || !/^[a-f0-9]{64}$/.test(expected))
+      return false;
+    if (hashMode === "codex-settings-v1") {
+      const prepared2 = prepareCodexSettingsV1(text2);
+      return receiptEdits(prepared2.config).some((edit) => {
+        const candidate = cloneTree(prepared2.config);
+        edit(candidate);
+        return finishCodexSettingsV1(candidate, prepared2.tokens) === expected;
+      });
+    }
+    const version2 = Number(hashMode.slice("codex-settings-v".length));
+    if (![2, 3, 4, 5].includes(version2))
+      return false;
+    const prepared = prepareSettings(text2, version2);
+    return receiptEdits(prepared.config).some((edit) => {
+      const candidate = cloneTree(prepared.config);
+      edit(candidate);
+      if (version2 >= 4 && isRecord3(candidate.tui) && !Object.keys(candidate.tui).length)
+        delete candidate.tui;
+      return finishSettings({ ...prepared, config: candidate }, version2) === expected;
+    });
+  } catch {
+    return false;
+  }
+}
+function codexSettingsWitnessMatch(path, hashMode, expected, budget2 = { remaining: 256 * 1024 * 1024 }) {
+  const text2 = readNativeSettingsWitnessFile(path, budget2, "config.toml");
+  need7(Buffer.byteLength(text2) <= 1024 * 1024);
+  const exact = hashMode === "codex-settings-v1" ? hashCodexSettingsReplacement(text2) : settingsDigest2(text2, Number(hashMode.slice("codex-settings-v".length)));
+  if (exact === expected)
+    return "exact";
+  return codexSettingsToleratesScreenReaderReceipt(text2, hashMode, expected) ? "screen-reader-receipt" : null;
+}
 function hashCodexSettingsReplacementV2(text2, budget2 = { remaining: 256 * 1024 * 1024 }) {
   need7(Buffer.byteLength(text2) <= 1024 * 1024 && budget2.remaining >= Buffer.byteLength(text2));
   budget2.remaining -= Buffer.byteLength(text2);
   return settingsDigest2(text2);
 }
-function captureCodexSettingsV2(path, budget2 = { remaining: 256 * 1024 * 1024 }) {
-  const text2 = readNativeSettingsWitnessFile(path, budget2, "config.toml");
-  return { path, hashMode: "codex-settings-v2", sha256: settingsDigest2(text2) };
-}
 function hashCodexSettingsReplacementV3(text2, budget2 = { remaining: 256 * 1024 * 1024 }) {
   need7(Buffer.byteLength(text2) <= 1024 * 1024 && budget2.remaining >= Buffer.byteLength(text2));
   budget2.remaining -= Buffer.byteLength(text2);
   return settingsDigest2(text2, 3);
 }
-function captureCodexSettingsV3(path, budget2 = { remaining: 256 * 1024 * 1024 }) {
-  return { path, hashMode: "codex-settings-v3", sha256: settingsDigest2(readNativeSettingsWitnessFile(path, budget2, "config.toml"), 3) };
-}
 function hashCodexSettingsReplacementV4(text2, budget2 = { remaining: 256 * 1024 * 1024 }) {
   need7(Buffer.byteLength(text2) <= 1024 * 1024 && budget2.remaining >= Buffer.byteLength(text2));
   budget2.remaining -= Buffer.byteLength(text2);
   return settingsDigest2(text2, 4);
 }
-function captureCodexSettingsV4(path, budget2 = { remaining: 256 * 1024 * 1024 }) {
-  return { path, hashMode: "codex-settings-v4", sha256: settingsDigest2(readNativeSettingsWitnessFile(path, budget2, "config.toml"), 4) };
-}
 function hashCodexSettingsReplacementV5(text2, budget2 = { remaining: 256 * 1024 * 1024 }) {
   need7(Buffer.byteLength(text2) <= 1024 * 1024 && budget2.remaining >= Buffer.byteLength(text2));
   budget2.remaining -= Buffer.byteLength(text2);
   return settingsDigest2(text2, 5);
 }
-function captureCodexSettingsV5(path, budget2 = { remaining: 256 * 1024 * 1024 }) {
-  return { path, hashMode: "codex-settings-v5", sha256: settingsDigest2(readNativeSettingsWitnessFile(path, budget2, "config.toml"), 5) };
-}
 function captureCodexSettingsV6(path, reviewedSources, budget2 = { remaining: 256 * 1024 * 1024 }, changes) {
   const original = readNativeSettingsWitnessFile(path, budget2, "config.toml");
   const text2 = changes?.get(path) ?? original;
@@ -33046,7 +33104,7 @@ function captureCodexSettingsV6(path, reviewedSources, budget2 = { remaining: 25
   need7(dependencies.servers.every((server) => !["codex_apps", "_codex_apps"].includes(server) && isCodexLocalStdioMcpServer(server, config2.mcp_servers?.[server])));
   return { path, hashMode: "codex-settings-v6", sha256: settingsDigest2(text2, 6, dependencies), hookSources: dependencies.sources };
 }
-var sha2 = (text2) => createHash13("sha256").update(text2).digest("hex"), EFFORT2, VERBOSITY2, MODEL, CODEX_DISCOVERY_PROJECTION_FIELDS, INFERENCE;
+var sha2 = (text2) => createHash13("sha256").update(text2).digest("hex"), EFFORT2, VERBOSITY2, MODEL, CODEX_DISCOVERY_PROJECTION_FIELDS, INFERENCE, SCREEN_READER_RECEIPT = "screen_reader_detection_done";
 var init_codex_settings_witness = __esm(() => {
   init_codex_settings_witness_v1();
   init_codex_settings_witness_v1();
@@ -35310,6 +35368,13 @@ var init_codex_semantic_cache_witness = __esm(() => {
   ]);
 });
 
+// src/lib/codex-node-modules.ts
+var PLUGIN_MANIFESTS;
+var init_codex_node_modules = __esm(() => {
+  init_claude_settings_witness();
+  PLUGIN_MANIFESTS = Object.freeze(["plugin.json", ".codex-plugin/plugin.json", ".claude-plugin/plugin.json", ".cursor-plugin/plugin.json"]);
+});
+
 // src/lib/managed-policy.ts
 import { closeSync as closeSync14, constants as constants11, fstatSync as fstatSync14, lstatSync as lstatSync17, openSync as openSync14, readSync as readSync8 } from "fs";
 import { join as join22 } from "path";
@@ -35838,6 +35903,7 @@ var init_agent_integration = __esm(() => {
   init_native_discovery_roots();
   init_codex_vendor_refresh();
   init_codex_native_skill_catalog();
+  init_codex_node_modules();
   init_config();
   init_managed_policy();
   init_agent_bridge();
@@ -37313,10 +37379,9 @@ function projected(source, changes, budget2 = discoveryByteBudget()) {
   if (source.hashMode === "codex-settings-v1" || source.hashMode === "codex-settings-v2" || (source.hashMode === "codex-settings-v3" || source.hashMode === "codex-settings-v4" || source.hashMode === "codex-settings-v5")) {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
       throw new Error("Codex settings witnesses require exact typed metadata");
-    const current = (source.hashMode === "codex-settings-v5" ? captureCodexSettingsV5 : source.hashMode === "codex-settings-v4" ? captureCodexSettingsV4 : source.hashMode === "codex-settings-v3" ? captureCodexSettingsV3 : source.hashMode === "codex-settings-v2" ? captureCodexSettingsV2 : captureCodexSettings)(source.path, budget2).sha256;
-    if (current !== source.sha256)
+    if (codexSettingsWitnessMatch(source.path, source.hashMode, source.sha256, budget2) === null)
       throw new NativeDiscoveryWitnessChange("input", source.path, `Native discovery input changed; run skills hook install with a fresh discovery review: ${source.path}`);
-    return changes?.has(source.path) ? (source.hashMode === "codex-settings-v5" ? hashCodexSettingsReplacementV5 : source.hashMode === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : current;
+    return changes?.has(source.path) ? (source.hashMode === "codex-settings-v5" ? hashCodexSettingsReplacementV5 : source.hashMode === "codex-settings-v4" ? hashCodexSettingsReplacementV4 : source.hashMode === "codex-settings-v3" ? hashCodexSettingsReplacementV3 : source.hashMode === "codex-settings-v2" ? hashCodexSettingsReplacementV2 : hashCodexSettingsReplacement)(changes.get(source.path), budget2) : source.sha256;
   }
   if (source.hashMode === "claude-settings-v1" || source.hashMode === "claude-settings-v2" || (source.hashMode === "claude-settings-v3" || source.hashMode === "claude-settings-v4")) {
     if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined || typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256))
@@ -37429,10 +37494,22 @@ function retiredCodexRoots(binding, tolerance) {
   }
   return proof.roots;
 }
-function retainableAbsentSource(source) {
+function retainableAbsentWitness(source) {
   if (source.format !== undefined || source.fields !== undefined || source.managedPlugins !== undefined)
-    return false;
-  return [undefined, "bytes"].includes(source.hashMode) || source.hashMode === "claude-plugin-manifest-v1" && source.sha256 !== null && source.path.endsWith(join30(sep11, ".claude-plugin", "plugin.json")) || source.hashMode === CLAUDE_ORPHAN_MARKER_MODE && source.sha256 !== null && isClaudePluginCacheOrphanMarker(source.path);
+    return null;
+  if ([undefined, "bytes"].includes(source.hashMode))
+    return "bytes";
+  if (source.hashMode === "claude-plugin-manifest-v1" && source.sha256 !== null && source.path.endsWith(join30(sep11, ".claude-plugin", "plugin.json")))
+    return "claude-plugin-manifest-v1";
+  if (source.hashMode === CLAUDE_ORPHAN_MARKER_MODE && source.sha256 !== null && isClaudePluginCacheOrphanMarker(source.path))
+    return CLAUDE_ORPHAN_MARKER_MODE;
+  return null;
+}
+function retainableAbsentSource(source) {
+  return retainableAbsentWitness(source) !== null;
+}
+function retainedAbsentRoot(absentRoots, source) {
+  return retainableAbsentSource(source) ? absentRoots.find((root) => source.path.startsWith(root + sep11)) : undefined;
 }
 function absentRetiredClaudeRoots(binding) {
   if (binding.agent !== "claude" || binding.method !== "reviewed")
@@ -37625,7 +37702,7 @@ function verifyAgentDiscovery(binding, codexRecovery, reviewedRootAliases, witne
       safe6(source.path);
       continue;
     }
-    if (absentRoots.some((root) => source.path.startsWith(root + sep11)) && retainableAbsentSource(source)) {
+    if (retainedAbsentRoot(absentRoots, source) !== undefined) {
       safe6(source.path);
       continue;
     }
@@ -37649,6 +37726,12 @@ function verifyAgentDiscovery(binding, codexRecovery, reviewedRootAliases, witne
       throw new Error("Retired native materialization changed during discovery verification");
   }
 }
+function claudeControlSource(source) {
+  return CLAUDE_CONTROL_WITNESS_MODES.has(source.hashMode ?? "") || CLAUDE_CONTROL_FILES.has(basename12(source.path)) && !source.path.includes(`${sep11}.claude${sep11}plugins${sep11}cache${sep11}`);
+}
+function retainedAbsentClaudeRoot(absentRoots, source) {
+  return claudeControlSource(source) ? undefined : retainedAbsentRoot(absentRoots, source);
+}
 function codexInstallationRoots(binding) {
   const proof = binding.codexInstallationInputs;
   if (proof === undefined)
@@ -37844,7 +37927,10 @@ function resolveAgentDiscovery(options) {
     if (!review.sources.some((source) => source.path === canonical9(configPath)))
       throw new Error("Discovery review must include the agent configuration source");
     const reviewedSources = supersedesSettingsProjection(agent, review.sources, canonical9(configPath)) ? sources.filter((source) => !isSupersededSettingsProjection(agent, canonical9(configPath), source)) : sources;
+    const absentRoots = absentRetiredClaudeRoots(supplied);
     const reviewedSourcesWithManifestProjection = review.sources.map((source) => {
+      if (retainedAbsentClaudeRoot(absentRoots, source) !== undefined)
+        return source;
       if (agent === "claude" && source.format === undefined && source.fields === undefined && source.managedPlugins === undefined && source.reviewArtifact === undefined && [undefined, "bytes", "path-bytes"].includes(source.hashMode) && isClaudePluginCacheOrphanMarker(source.path)) {
         return { path: source.path, hashMode: CLAUDE_ORPHAN_MARKER_MODE, sha256: hashClaudePluginCacheOrphanMarker(source.path) };
       }
@@ -37877,6 +37963,11 @@ function resolveAgentDiscovery(options) {
     });
     if (agent === "claude")
       assertReviewedClaudeCacheClosures(home, config2, review, canonical9);
+    for (const root of absentRoots) {
+      safe6(root);
+      if (lstatSync23(root, { throwIfNoEntry: false }))
+        throw new Error("Retired native materialization changed during discovery review");
+    }
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate) => isDeepStrictEqual5(candidate, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };
@@ -37999,7 +38090,7 @@ var DISCOVERY_RUNTIME_COMMANDS, realpathOrNull = (path) => {
   } catch {
     return null;
   }
-}, digest2 = (text2) => createHash24("sha256").update(text2).digest("hex");
+}, digest2 = (text2) => createHash24("sha256").update(text2).digest("hex"), CLAUDE_CONTROL_WITNESS_MODES, CLAUDE_CONTROL_FILES, ADOPTABLE_SETTINGS_MATCHES, CLAUDE_PROJECT_DISCOVERY_KEYS;
 var init_agent_discovery = __esm(() => {
   init_sumi_settings_witness();
   init_agent_policy_limits();
@@ -38029,6 +38120,10 @@ var init_agent_discovery = __esm(() => {
   init_codex_semantic_cache_witness();
   init_agent_discovery_directories();
   DISCOVERY_RUNTIME_COMMANDS = Object.freeze({ gemini: "gemini" });
+  CLAUDE_CONTROL_WITNESS_MODES = new Set(["claude-settings-v1", "claude-settings-v2", "claude-settings-v3", "claude-settings-v4", "claude-marketplace-registry", "claude-marketplace-registry-v2", "claude-marketplace-entry-v1", "claude-plugin-registry"]);
+  CLAUDE_CONTROL_FILES = new Set(["settings.json", "settings.local.json", "installed_plugins.json", "known_marketplaces.json"]);
+  ADOPTABLE_SETTINGS_MATCHES = Object.freeze(["exact", "screen-reader-receipt"]);
+  CLAUDE_PROJECT_DISCOVERY_KEYS = Object.freeze(["enabledPlugins", "extraKnownMarketplaces", "additionalMarketplaces", "skillOverrides"]);
 });
 
 // src/lib/authoring-path.ts
@@ -46318,7 +46413,11 @@ var exports_selected_run = {};
 __export(exports_selected_run, {
   resolveSelectedRun: () => resolveSelectedRun,
   prepareSelectedSecretBindings: () => prepareSelectedSecretBindings,
-  executeSelectedLocal: () => executeSelectedLocal
+  instructionRunRefusal: () => instructionRunRefusal,
+  instructionEntrypointMismatch: () => instructionEntrypointMismatch,
+  instructionCommandEntry: () => instructionCommandEntry,
+  executeSelectedLocal: () => executeSelectedLocal,
+  declaredOperation: () => declaredOperation
 });
 import { createHash as createHash28 } from "crypto";
 import { spawn as spawn2 } from "child_process";
@@ -46331,12 +46430,51 @@ async function resolveSelectedRun(spec, profileId, options = {}) {
   const entries = await readSelectedEntries(selection2, context2, options);
   return { selection: selection2, profileId: context2.receipt.profile.profileId, entries, ...describeEntries(entries), cacheDir: selectionCacheRoot(options) };
 }
+function declaredOperation(manifest) {
+  const entry = instructionCommandEntry(manifest);
+  if (!entry)
+    return null;
+  const runtime = manifest.runtime;
+  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime))
+    return null;
+  if (runtime.runtime !== "bun" && runtime.runtime !== "node" && runtime.runtime !== "python3")
+    return null;
+  if (instructionEntrypointMismatch(manifest))
+    return null;
+  return { entry };
+}
+function instructionCommandEntry(manifest) {
+  const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+  const command = commands[0];
+  if (!command || typeof command !== "object" || typeof command.entry !== "string" || command.entry.length === 0)
+    return null;
+  return command.entry;
+}
+function instructionEntrypointMismatch(manifest) {
+  const entry = instructionCommandEntry(manifest);
+  const declared = manifest.runtime;
+  if (!entry || !declared || typeof declared !== "object" || Array.isArray(declared))
+    return null;
+  const runtimeEntrypoint = declared.entrypoint;
+  return typeof runtimeEntrypoint === "string" && runtimeEntrypoint !== entry ? runtimeEntrypoint : null;
+}
+function instructionRunRefusal(manifest, isBundledFile) {
+  const declaredEntry = instructionCommandEntry(manifest);
+  if (declaredEntry && !isBundledFile(declaredEntry))
+    return { code: "LOCAL_ENTRYPOINT_MISSING", message: `This selected instruction skill declares its operation entry as ${declaredEntry}, which is not a regular file in the selected bundle; a different runtime.entrypoint never substitutes for it.` };
+  const mismatch = instructionEntrypointMismatch(manifest);
+  if (mismatch)
+    return { code: "LOCAL_ENTRYPOINT_MISMATCH", message: `This selected instruction skill declares its operation entry as ${declaredEntry}, but its runtime.entrypoint is ${mismatch}; the two must agree.` };
+  if (!declaredOperation(manifest))
+    return { code: "INSTRUCTION_SKILL", message: "This selected skill contains instructions. Use skills load instead of skills run." };
+  return null;
+}
 async function prepareSelectedSecretBindings(selected, cwd = process.cwd()) {
   const entries = await readCachedSelection(selected.selection, { cacheDir: selected.cacheDir });
   if (!entries)
     throw new SkillSelectionError("CACHED_BUNDLE_MISSING", "The selected execution bundle is not cached.");
   const { kind, manifest } = describeEntries(entries);
-  if (kind !== "executable")
+  if (kind !== "executable" && !declaredOperation(manifest))
     throw new SkillSelectionError("INSTRUCTION_SKILL", "Instruction skills do not accept execution secret bindings.");
   const names = declaredSecretNames(manifest.runtime?.env);
   if (!names.length)
@@ -46349,8 +46487,12 @@ async function executeSelectedLocal(selected, options = {}) {
   if (!entries)
     throw new SkillSelectionError("CACHED_BUNDLE_MISSING", "The selected local execution bundle is not cached.");
   const { kind, manifest, packageJson } = describeEntries(entries);
-  if (kind === "instruction")
-    throw new SkillSelectionError("INSTRUCTION_SKILL", "This selected skill contains instructions. Use skills load instead of skills run.");
+  const operation = declaredOperation(manifest);
+  if (kind === "instruction") {
+    const refusal3 = instructionRunRefusal(manifest, (path) => entries.some((entry) => entry.path === path));
+    if (refusal3)
+      throw new SkillSelectionError(refusal3.code, refusal3.message);
+  }
   const runtime = manifest.runtime ?? {};
   if (!runtime || typeof runtime !== "object" || Array.isArray(runtime))
     throw new SkillSelectionError("INVALID_SKILL_MANIFEST", "The selected runtime declaration is invalid.");
@@ -46369,9 +46511,9 @@ async function executeSelectedLocal(selected, options = {}) {
   const executable = runtimeName === "bun" ? process.execPath : Bun.which(runtimeName);
   if (!executable)
     throw new SkillSelectionError("LOCAL_RUNTIME_UNAVAILABLE", "The selected runtime is not installed on this station.");
-  const declaredEntry = runtime.entrypoint ?? (typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin && typeof packageJson.bin === "object" ? Object.values(packageJson.bin)[0] : undefined);
+  const declaredEntry = (kind === "instruction" ? operation?.entry : undefined) ?? runtime.entrypoint ?? (typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin && typeof packageJson.bin === "object" ? Object.values(packageJson.bin)[0] : undefined);
   if (typeof declaredEntry !== "string" || !entries.some((entry) => entry.path === declaredEntry))
-    throw new SkillSelectionError("LOCAL_ENTRYPOINT_MISSING", "The selected bundle must declare a regular-file entrypoint in its runtime manifest or package bin.");
+    throw new SkillSelectionError("LOCAL_ENTRYPOINT_MISSING", kind === "instruction" ? "The selected instruction skill must declare the operation entrypoint it ships in its manifest, and that declared entry must be a regular file in the selected bundle; a different runtime.entrypoint never substitutes for it." : "The selected bundle must declare a regular-file entrypoint in its runtime manifest or package bin.");
   const args = options.args ?? [];
   if (args.length > 128 || args.some((arg) => typeof arg !== "string" || arg.length > 16384 || arg.includes("\x00")))
     throw new SkillSelectionError("INVALID_RUN_INPUT", "Local skill arguments exceed their limits.");
@@ -46446,6 +46588,7 @@ async function executeSelectedLocal(selected, options = {}) {
     selection: selection2,
     target: "local",
     runtime: runtimeName,
+    entrypoint: declaredEntry,
     inputDigest: `sha256:${createHash28("sha256").update(input2).digest("hex")}`,
     runDirectory,
     ...executionGrant ? { executionGrant } : {},
@@ -46892,13 +47035,18 @@ function registerOperationTools(server) {
       return mcpError("CONFLICTING_EXECUTION_MODES", "Use remote for the configured server catalog and quote, or target for selected execution, not both.");
     if (managed && !remote) {
       try {
-        const { resolveSelectedRun: resolveSelectedRun2, executeSelectedLocal: executeSelectedLocal2 } = await Promise.resolve().then(() => (init_selected_run(), exports_selected_run));
+        const { resolveSelectedRun: resolveSelectedRun2, executeSelectedLocal: executeSelectedLocal2, instructionRunRefusal: instructionRunRefusal2 } = await Promise.resolve().then(() => (init_selected_run(), exports_selected_run));
         const resolved = await resolveSelectedRun2(name, selectedProfileId(), { projectDir: process.cwd() });
-        if (resolved.kind === "instruction")
-          return mcpError("INSTRUCTION_SKILL", "This selected skill contains instructions. Load it with skills load instead of running it.");
+        if (resolved.kind === "instruction") {
+          const refusal3 = instructionRunRefusal2(resolved.manifest, (path) => resolved.entries.some((entry) => entry.path === path));
+          if (refusal3)
+            return mcpError(refusal3.code, refusal3.message);
+        }
         if (files?.length)
           return mcpError("SELECTED_INPUT_REQUIRED", "Selected executions require their declared JSON input; use the CLI cloud execution input contract for files.");
         if (target === "cloud") {
+          if (resolved.kind === "instruction")
+            return mcpError("INSTRUCTION_SKILL", "Cloud execution requires an executable skill version; run the declared operation locally on a managed station, or load the instructions with skills load.");
           if (args?.length || quoteReceipt || maxCredits !== undefined || maxCostCents !== undefined)
             return mcpError("SELECTED_INPUT_REQUIRED", "The selected cloud execution contract accepts declared JSON input, not legacy run arguments or quote receipts.");
           const { CloudExecutionClient: CloudExecutionClient2 } = await Promise.resolve().then(() => (init_cloud_executions(), exports_cloud_executions));

package/bin/migrate.js

@@ -25,7 +25,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.72",
+  version: "0.10.74",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24140,7 +24140,7 @@ restoreLaunchCwd();
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.72",
+  version: "0.10.74",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24143,7 +24143,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.72",
+  version: "0.10.74",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/cli/commands/provenance.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from "commander";
+import { type SelectionProvenanceReceipt } from "../../lib/selection-provenance.js";
+export interface ProvenanceCommandOptions {
+    selectionProfile?: string;
+    station?: string;
+    session?: string;
+    cached?: boolean;
+    json?: boolean;
+}
+/**
+ * One read-only receipt for the selection chain: selected, activated, applied,
+ * pinned and consumed are named separately, and every consumer carries its
+ * status and reason. An exit code here only reports a bad request: a read that
+ * could not be answered is recorded as `unverified`, because that is the fact
+ * the caller came for.
+ */
+export declare function provenanceLines(receipt: SelectionProvenanceReceipt): string[];
+export declare function registerProvenance(parent: Command): void;