@hasna/skills 0.10.73 → 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.73",
+    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));
@@ -37726,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)
@@ -37921,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) };
       }
@@ -37954,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 } : {} };
@@ -46399,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";
@@ -46412,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)
@@ -46430,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.");
@@ -46450,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.");
@@ -46527,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 } : {},
@@ -46973,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.73",
+  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.73",
+  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.73",
+  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;

package/dist/index.js

@@ -8566,8 +8566,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(join6(skillPath, "SKILL.md"))) {
     writeFileSync2(join6(skillPath, "SKILL.md"), renderSkillMd(next));
@@ -15144,7 +15144,7 @@ import { basename as basename13, dirname as dirname24, isAbsolute as isAbsolute2
 import { homedir as homedir5 } from "os";
 import { isAbsolute as isAbsolute25, join as join36, resolve as resolve24 } from "path";
 // package.json
-var version = "0.10.73";
+var version = "0.10.74";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -20212,11 +20212,19 @@ function planAgentIntegration(options) {
     const executable2 = discoveryExecutable(agent) ?? (prior ? recordedDiscoveryExecutable(agent, prior) : null);
     executables.set(agent, executable2);
     const retainedReview = options.discoveryInputs === undefined && policy.bridge?.discovery?.[agent]?.method === "reviewed" ? { ...policy.bridge.discovery[agent], ...agent === "codex" ? { codexDisabledPluginSkills: policy.bridge.codexPluginSkills ?? [] } : {} } : undefined;
-    if (retainedReview) {
-      assertManagedAgentBridge(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
-      retainedAgents.push(agent);
+    try {
+      if (retainedReview) {
+        assertRetainedReviewState(agent, { home, dataDir: dataDir2, projectDir: options.projectDir ?? home });
+        retainedAgents.push(agent);
+      }
+      return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
+    } catch (error) {
+      if (isDiscoveryRootUnresolved(error) || error instanceof SumiPathResolverError || error instanceof NativeSkillCopiesDriftError)
+        throw error;
+      if (!retainedReview)
+        throw error;
+      throw new Error(`NATIVE_SKILL_DRIFT: ${error.message.replace(/^NATIVE_SKILL_DRIFT: /, "")}. This agent reuses a saved discovery review and that review no longer verifies, so a fresh explicit review is required: skills hook install --agent ${agent} --discovery-inputs <review> --apply.`);
     }
-    return resolveAgentDiscovery({ home, agent, reviewed: options.discoveryInputs, retainedReview, canonical: (path) => canonicalAgentPath(path, aliases), executable: executable2 });
   });
   const codexConfigBefore = options.agents.includes("codex") ? readOptional(canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases)) : null;
   const codexConfig = Bun.TOML.parse(codexConfigBefore ?? "");
@@ -20970,7 +20978,7 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   assertCurrent();
   recheckRootAliases(aliases);
   for (const agent of plan.retainedReviewChecks?.agents ?? [])
-    assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
+    assertRetainedReviewState(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
   if (plan.reviewArtifactMigration) {
     const verified = planReviewedArtifactMigration(plan.reviewArtifactMigration);
     if (JSON.stringify(verified.changes) !== JSON.stringify(plan.changes) || JSON.stringify(verified.discoveryAfter) !== JSON.stringify(plan.discoveryAfter))
@@ -21013,6 +21021,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
   if (!plan.changes.length) {
     assertCurrent();
     recheckRootAliases(aliases);
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     return { changed: [], backups, ...aliases.length ? { rootAliases: aliases } : {} };
   }
   assertSafePath(backupRoot);
@@ -21062,6 +21072,8 @@ function applyAgentIntegrationUnlocked(plan, options = {}, assertCurrent) {
     }
     for (const agent of plan.managedAgentChecks?.agents ?? [])
       assertManagedAgentBridge(agent, { home: plan.managedAgentChecks.home, dataDir: plan.dataDir, projectDir: plan.managedAgentChecks.projectDir ?? plan.managedAgentChecks.home });
+    for (const agent of plan.retainedReviewChecks?.agents ?? [])
+      assertManagedAgentBridge(agent, { ...plan.retainedReviewChecks, dataDir: plan.dataDir });
     atomicWrite2(join31(backupRoot, "receipt.json"), JSON.stringify({ version: 1, changes: written.map((change) => ({ path: change.path, beforeHash: change.before === null ? null : sha4(change.before), afterHash: sha4(change.after) })), backups, ...plan.cacheWitnessUpgrade ? { cacheWitnessUpgrade: plan.cacheWitnessUpgrade } : {}, ...plan.retainedReviewArtifacts?.length ? { retainedReviewArtifacts: plan.retainedReviewArtifacts.map((item) => ({ path: item.path, ...item.artifact })) } : {}, ...aliases.length ? { rootAliases: aliases } : {} }) + `
 `);
   } catch (error) {
@@ -21393,7 +21405,7 @@ enabled = false
 function assertManagedAgentBridge(agent, options = {}) {
   return assertManagedAgentBridgeWithDiscovery(agent, options);
 }
-function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+function assertManagedBridgeCustody(agent, options = {}, provenDiscovery) {
   const home = resolve23(options.home ?? homedir2()), dataDir2 = options.dataDir ?? getDataDirReadOnly();
   assertSafePath(join31(dataDir2, "agent-policy.json"));
   const snapshot2 = readManagedSkillPolicySnapshot(dataDir2);
@@ -21410,7 +21422,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (!isOwnedCliBridge(expected, [expected]))
     throw new Error("NATIVE_SKILL_DRIFT: the native Skills bridge is missing or modified; repair it before continuing");
   const roots = projectAncestorDirectories([options.projectDir ?? process.cwd(), ...options.projectDirs ?? [], ...agent === "hermes" && process.env.TERMINAL_CWD ? [process.cwd()] : []]);
-  const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const discovery = provenDiscovery ?? binding.discovery?.[agent];
   assertProjectDiscovery(agent, [...roots], home, (path) => canonicalAgentPath(path, aliases), discovery);
   for (const source of discovery?.sources ?? [])
@@ -21425,11 +21436,30 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     throw new Error("NATIVE_SKILL_DRIFT: the native hook command/profile binding is missing");
   if (options.profileId !== undefined && options.profileId !== profile)
     throw new Error("NATIVE_SKILL_DRIFT: the hook selection profile differs from its managed binding; restart the native client after reviewing skills hook install");
+  return { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery, configPath, config, command, profile };
+}
+function assertUnrepairableBridgeProtection(custody, agent) {
+  if (agent !== "hermes")
+    return;
+  const { home, dataDir: dataDir2, binding, config, command, profile } = custody;
+  const supervisor = binding.supervisors?.hermes;
+  if (supervisor?.path !== join31(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha4(renderHermesSupervisor(command, profile)))
+    throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
+  assertHermesProtection(home, config, command, profile, supervisor);
+}
+function assertRetainedReviewState(agent, options) {
+  const custody = assertManagedBridgeCustody(agent, options);
+  assertUnrepairableBridgeProtection(custody, agent);
+  assertManagedNativeDiscovery(custody, agent, options);
+}
+
+class NativeSkillCopiesDriftError extends Error {
+}
+function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscovery) {
+  const custody = assertManagedBridgeCustody(agent, options, provenDiscovery);
+  const { home, aliases, expected, discovery, config, command, profile } = custody;
   if (agent === "hermes") {
-    const supervisor = binding.supervisors?.hermes;
-    if (supervisor?.path !== join31(dataDir2, "agent-hooks", "hermes.js") || supervisor?.sha256 !== sha4(renderHermesSupervisor(command, profile)))
-      throw new Error("NATIVE_SKILL_DRIFT: Hermes supervisor binding changed; run skills hook install");
-    assertHermesProtection(home, config, command, profile, supervisor);
+    assertUnrepairableBridgeProtection(custody, agent);
   } else if (agent === "sumi") {
     if (JSON.stringify(config.permissions?.filter((rule) => rule.action === "skill")) !== JSON.stringify(SUMI_SKILL_PERMISSIONS) || !isManagedSumiPlugin(readOptional(join31(sumiConfigDirectory(home, process.env, options.projectDir ?? process.cwd()), "plugins", "skills-cli.js")), command, profile))
       throw new Error("NATIVE_SKILL_DRIFT: Sumi bridge protection changed; run skills hook install");
@@ -21451,6 +21481,21 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
     if (agent === "gemini" && (config.hooksConfig?.enabled === false || config.skills?.enabled !== true || !["antigravity-support", "skill-creator"].every((name) => config.skills?.disabled?.includes(name)) || config.skills?.disabled?.includes(CLI_BRIDGE_NAME)))
       throw new Error("NATIVE_SKILL_DRIFT: Gemini bridge or bundled-skill protection changed; run skills hook install");
   }
+  if (agent === "codex") {
+    const codexConfig = Bun.TOML.parse(readOptional(canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases)) ?? "");
+    if (codexConfig.skills?.bundled?.enabled !== false)
+      throw new Error("NATIVE_SKILL_DRIFT: Codex bundled skill reseeding is not disabled (skills.bundled.enabled); run skills hook install");
+    const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join31(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
+    if ([...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
+      throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
+  }
+  if (agent === "gemini" && discovery && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
+    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
+  return assertManagedNativeDiscovery(custody, agent, options);
+}
+function assertManagedNativeDiscovery(custody, agent, options) {
+  const { home, dataDir: dataDir2, binding, aliases, expected, roots, discovery } = custody;
+  const visible = (entry) => entry.agent === agent || ["codex", "gemini", "opencode", "hermes", "sumi"].includes(agent) && entry.path.includes(`${sep14}.agents${sep14}skills${sep14}`) || ["opencode", "sumi"].includes(agent) && entry.agent === "claude";
   const codexPath = canonicalAgentPath(join31(home, ".codex", "config.toml"), aliases);
   const vendorCache = canonicalAgentPath(join31(home, ".codex", "plugins", "cache"), aliases);
   const witnessTolerance = agent === "codex" && options.codexPromptHook === true ? {
@@ -21461,11 +21506,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   if (options.codexDiscoveryRecovery && (agent !== "codex" || options.codexDiscoveryRecovery.configPath !== codexPath))
     throw new Error("NATIVE_SKILL_DRIFT: Codex trust recovery names a different configuration root");
   const codexConfig = agent === "codex" ? Bun.TOML.parse(readOptional(codexPath) ?? "") : {};
-  if (agent === "codex" && codexConfig.skills?.bundled?.enabled !== false)
-    throw new Error("NATIVE_SKILL_DRIFT: Codex bundled skill reseeding is not disabled (skills.bundled.enabled); run skills hook install");
-  const setting = (path) => (codexConfig.skills?.config ?? []).filter((entry) => typeof entry.path === "string" && [path, join31(path, "SKILL.md")].includes(canonicalAgentPath(entry.path, aliases)));
-  if (agent === "codex" && [...setting(expected), ...(codexConfig.skills?.config ?? []).filter((entry) => typeof entry.name === "string" && entry.name.trim() === CLI_BRIDGE_NAME)].some((entry) => entry.enabled === false))
-    throw new Error("NATIVE_SKILL_DRIFT: the Codex CLI bridge is disabled; run skills hook install");
   if (agent === "codex" && !reviewedCodexPluginCapabilitiesUnchanged(canonicalAgentPath(join31(home, ".codex/plugins/cache"), aliases), binding.codexPluginSkills ?? [], (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)), codexConfig.skills?.config ?? []))
     throw new Error("NATIVE_SKILL_DRIFT: reviewed native plugin capability controls changed; run skills hook install with a fresh discovery review");
   const disabledPlugin = (entry) => {
@@ -21502,8 +21542,6 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
   };
   if (!discovery || discovery.agent !== agent)
     throw new Error("NATIVE_SKILL_DRIFT: native discovery coverage is missing; run skills hook install");
-  if (agent === "gemini" && !discovery.builtinNames?.every((name) => config.skills.disabled.includes(name)))
-    throw new Error("NATIVE_SKILL_DRIFT: an installed Gemini builtin is not disabled");
   try {
     verifyAgentDiscovery(agent === "codex" ? { ...discovery, codexDisabledPluginSkills: binding.codexPluginSkills ?? [] } : discovery, options.codexDiscoveryRecovery, aliases, witnessTolerance);
     if (agent === "sumi" && discovery.method === "reviewed")
@@ -21558,7 +21596,7 @@ function assertManagedAgentBridgeWithDiscovery(agent, options = {}, provenDiscov
         return false;
       }
     }, read: (path) => new TextDecoder("utf-8", { fatal: true }).decode(readNativeBytes(path, 1024 * 1024)) });
-    throw new Error(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
+    throw new NativeSkillCopiesDriftError(`NATIVE_SKILL_DRIFT: ${blocking.length} unexpected native skill copies were found: ${nativeSkillPathList(blocking.map((entry) => entry.path))}. ${remediation}${adapterRefusal ? ` Native policy adapter refused: ${adapterRefusal}` : ""}`);
   }
   recheckRootAliases(aliases);
   const discoveryChanges = (witnessTolerance?.changes ?? []).filter((change, index, all) => all.findIndex((other) => other.kind === change.kind && other.path === change.path) === index);
@@ -24133,6 +24171,12 @@ function verifyAgentDiscovery(binding, codexRecovery, reviewedRootAliases, witne
 }
 var 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"]);
 var CLAUDE_CONTROL_FILES = new Set(["settings.json", "settings.local.json", "installed_plugins.json", "known_marketplaces.json"]);
+function claudeControlSource(source) {
+  return CLAUDE_CONTROL_WITNESS_MODES.has(source.hashMode ?? "") || CLAUDE_CONTROL_FILES.has(basename15(source.path)) && !source.path.includes(`${sep15}.claude${sep15}plugins${sep15}cache${sep15}`);
+}
+function retainedAbsentClaudeRoot(absentRoots, source) {
+  return claudeControlSource(source) ? undefined : retainedAbsentRoot(absentRoots, source);
+}
 function codexInstallationRoots(binding) {
   const proof = binding.codexInstallationInputs;
   if (proof === undefined)
@@ -24542,7 +24586,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) };
       }
@@ -24575,6 +24622,11 @@ function resolveAgentDiscovery(options) {
     });
     if (agent === "claude")
       assertReviewedClaudeCacheClosures(home, config, review, canonical9);
+    for (const root2 of absentRoots) {
+      safe6(root2);
+      if (lstatSync32(root2, { throwIfNoEntry: false }))
+        throw new Error("Retired native materialization changed during discovery review");
+    }
     const combined = [...reviewedSources, ...reviewedSourcesWithManifestProjection];
     const unique = combined.filter((source, index) => combined.findIndex((candidate2) => isDeepStrictEqual9(candidate2, source)) === index);
     return { ...supplied, roots: [...new Set([...roots, ...supplied.roots])].sort(), sources: unique, ...agent === "gemini" ? { builtinNames } : {} };

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.73";
+var version = "0.10.74";
 var package_default = {
   name: "@hasna/skills",
   version,